Update AGENTS.md生成器 skill in marketplace

Constraint: Public skills are published only by explicit administrator action unless they are tracked third-party market sources. Confidence: high Scope-risk: narrow Directive: Keep private/internal skills out of the public marketplace and preserve normal incremental market Git history. Tested: Marketplace validation passed.
2026-06-18 16:56:08 +08:00
parent 06cd1c41c5
commit 0ad0decf6e
3 changed files with 17 additions and 12 deletions
@@ -12,20 +12,20 @@ Create lean, scoped, verifiable `AGENTS.md` files from repository facts. Treat r
 ## Workflow

 1. **Scan facts before drafting.** Inspect existing `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, tool rules, manifests, CI, key directories, and docs. Use `rg --files` first. Record unknowns instead of guessing.
-2. **Extract only verifiable facts.** Commands must come from files such as `package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`, CI workflows, or repo docs. Paths must exist.
+2. **Extract only verifiable facts.** Commands must come from files such as `package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`, CI workflows, or repo docs. Paths must exist. Omit any command, path, or section that cannot be verified; report the gap in the final response instead of adding placeholders.
 3. **Choose the scope model.**
   - Use one root file for small repos with shared commands and conventions.
   - Use root plus child `AGENTS.md` files for monorepos or directories with distinct commands, risks, or conventions.
   - Keep complex task workflows in skills or references, not in always-on `AGENTS.md`.
 4. **Draft with the standard contract.** Read `references/agents-md-reference.md` for root and child templates, section guidance, and validation criteria.
 5. **Update conservatively.** If `AGENTS.md` already exists, merge rather than replace. Preserve user-written sections unless they are clearly stale or conflict with verified facts. Show conflicts before changing them when possible.
-6. **Validate before finishing.** Run the bundled validator when applicable:
+6. **Validate before finishing.** Run the bundled validator when applicable. Use `--local` for child guides, and use `--warnings-as-errors` only when the user or repo explicitly wants strict gating:

 ```bash
 python path/to/generate-agents-md/scripts/validate_agents_md.py --repo /path/to/repo --file /path/to/repo/AGENTS.md
 ```

-Also run repo-native markdown/prose checks if they exist.
+Treat validator warnings as review prompts. Do not add unverifiable sections just to silence a warning. Also run repo-native markdown/prose checks if they exist.

 ## Content Placement

@@ -40,6 +40,7 @@ Also run repo-native markdown/prose checks if they exist.

 - Keep root files concise, usually under 200 lines.
 - Use exact commands, exact paths, and concrete rules.
+- Keep recommended sections only when they contain verified content.
 - Prefer `Always`, `Ask first`, and `Never` boundaries for risk.
 - State user instructions override repo guidance; child files override parent files for their directory.
 - Do not include secrets, internal credentials, or unverifiable environment assumptions.
@@ -63,3 +64,4 @@ Report:
 | Child guide repeats parent rules | Keep only local differences |
 | Existing custom guidance is overwritten | Merge and preserve non-conflicting user content |
 | Placeholder text remains | Replace with verified facts or write `Unknown` in review notes, not in final guide |
+| Validator warnings are treated as required content | Investigate warnings, but omit sections that lack verified facts |
@@ -81,7 +81,7 @@ Root files should orient. Child files should specialize.
 - `docs/file.md` - when to read it
 ```

-Remove sections that have no verified content. Do not leave placeholder text.
+Remove sections that have no verified content. Do not leave placeholder text. `Project Overview` and `Scope` usually belong in every root guide; the other template sections are recommended when the repository has facts to support them.

 ## Child Template

@@ -106,7 +106,7 @@ Remove sections that have no verified content. Do not leave placeholder text.
 - Never: [local forbidden edits]
 ```

-If a child directory has no distinct commands, omit `Local Commands` rather than inventing commands.
+If a child directory has no distinct commands, omit `Local Commands` rather than inventing commands. Keep `Local Purpose` and `Inherits` in normal child guides; include `Local Conventions` and `Local Risks` only when there are local facts worth capturing.

 ## Scoring Checklist

@@ -115,6 +115,7 @@ A strong guide passes these checks:
 - **Specific:** Every command and path is concrete.
 - **Verified:** Commands and paths trace to repository files.
 - **Scoped:** Root guidance stays global; child guidance contains only local differences.
+- **No filler:** Missing recommended sections are acceptable when there is no verified content.
 - **Short:** Root is usually under 200 lines and avoids long procedures.
 - **Actionable:** A new agent can find the right files, run the right checks, and avoid high-risk edits.
 - **Compatible:** It states parent/child precedence and user-instruction precedence.
@@ -2,8 +2,8 @@
 """Lightweight AGENTS.md validator.

 Checks for common problems before an agent guide is treated as done:
-missing sections, placeholders, nonexistent referenced paths, and package
-manager commands that do not map to package.json scripts.
+missing recommended sections, placeholders, nonexistent referenced paths, and
+package manager commands that do not map to package.json scripts.
 """

 from __future__ import annotations
@@ -26,7 +26,7 @@ PLACEHOLDER_RE = re.compile(
 CODE_SPAN_RE = re.compile(r"`([^`\n]+)`")
 HEADING_RE = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)

-ROOT_REQUIRED_HEADINGS = {
+ROOT_RECOMMENDED_HEADINGS = {
    "Project Overview",
    "Scope",
    "Quick Commands",
@@ -35,7 +35,7 @@ ROOT_REQUIRED_HEADINGS = {
    "Boundaries",
 }

-LOCAL_REQUIRED_HEADINGS = {
+LOCAL_RECOMMENDED_HEADINGS = {
    "Local Purpose",
    "Inherits",
    "Local Conventions",
@@ -68,6 +68,8 @@ def normalize_path_token(token: str) -> str | None:
        return None
    if any(part in token for part in ("&&", "||", " --", " -")):
        return None
+    if any(char in token for char in "*?[]"):
+        return None
    if token in {"AGENTS.md", "CLAUDE.md", "README.md"}:
        return token
    if PATH_HINT_RE.search(token):
@@ -98,10 +100,10 @@ def validate(args: argparse.Namespace) -> tuple[list[str], list[str]]:
    text = guide.read_text(encoding="utf-8")
    headings = set(HEADING_RE.findall(text))

-    required = LOCAL_REQUIRED_HEADINGS if args.local else ROOT_REQUIRED_HEADINGS
-    missing = sorted(required - headings)
+    recommended = LOCAL_RECOMMENDED_HEADINGS if args.local else ROOT_RECOMMENDED_HEADINGS
+    missing = sorted(recommended - headings)
    if missing:
-        errors.append("Missing recommended headings: " + ", ".join(missing))
+        warnings.append("Missing recommended headings: " + ", ".join(missing))

    placeholders = sorted(set(match.group(0) for match in PLACEHOLDER_RE.finditer(text)))
    if placeholders: