From 0ad0decf6e45ba91dcc1f5c459a26f6b79335fd0 Mon Sep 17 00:00:00 2001 From: KeyInfo Bot Date: Thu, 18 Jun 2026 16:56:08 +0800 Subject: [PATCH] =?UTF-8?q?Update=20AGENTS.md=E7=94=9F=E6=88=90=E5=99=A8?= =?UTF-8?q?=20skill=20in=20marketplace?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../skills/generate-agents-md/SKILL.md | 8 +++++--- .../references/agents-md-reference.md | 5 +++-- .../scripts/validate_agents_md.py | 16 +++++++++------- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/SKILL.md b/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/SKILL.md index 410889887..08d851a3e 100644 --- a/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/SKILL.md +++ b/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/SKILL.md @@ -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 | diff --git a/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/references/agents-md-reference.md b/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/references/agents-md-reference.md index d9e0260a1..54a468782 100644 --- a/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/references/agents-md-reference.md +++ b/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/references/agents-md-reference.md @@ -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. diff --git a/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/scripts/validate_agents_md.py b/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/scripts/validate_agents_md.py index b80d7d9e3..a1e2593d8 100644 --- a/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/scripts/validate_agents_md.py +++ b/plugins/codex/plugins/generate-agents-md/skills/generate-agents-md/scripts/validate_agents_md.py @@ -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: