{"slug": "agents-md-authoring-skill", "title": "AGENTS.md authoring skill", "summary": "A developer has published a structured skill for authoring and auditing AGENTS.md files, designed to produce short, scoped guidance that changes agent behavior without restating obvious codebase facts. The skill enforces a workflow of suggesting changes before editing, compressing bloated files, and preserving only non-obvious deltas such as project direction, non-negotiables, and architecture seams. It provides templates for repo-level and nested files, and supports modes including audit, draft, rewrite, and split.", "body_md": "| name | agents-md |\n|---|---|\n| description | How to write, audit and edit AGENTS.md files. |\n\nCreate and improve AGENTS.md files that are short, scoped, and useful to coding agents. Preserve intent and non-obvious rules; do not summarize the repo.\n\n- Suggest changes before editing; discuss first unless the user explicitly asks for direct edits.\n- Normal repo/brownfield AGENTS.md should aim for ~20 lines or less.\n- Do not restate what an agent can infer from code, package files, folder names, or a quick search.\n- Prefer compressed, high-signal half-sentences over full prose, except for greenfield/founder notes and personal/global files.\n- Nested AGENTS.md files should mostly contain local edge cases, local pointers, or skill/doc routing.\n- Use RFC2119 caps (\n`MUST`\n\n,`SHOULD`\n\n,`REQUIRED`\n\n) sparingly for true non-negotiables. - Do not use XML-ish wrappers by default.\n\n- Target path or repo/folder scope.\n- Desired mode: audit, suggest, draft, rewrite, split, or create missing root guidance.\n- Project type when known: greenfield, brownfield, nested, or personal/global.\n- User intent, preferences, or comments about tone/strictness.\n\nIf the target or project type is unclear, inspect briefly and infer. Ask only when the edit direction or blast radius is ambiguous.\n\n-\n**Scope the work.**- Identify whether the target is repo-level, nested, greenfield, brownfield, or personal/global.\n- Stay inside the user-requested scope. Do not wander into unrelated dependencies or archives just because they contain AGENTS.md.\n\n-\n**Inspect only what matters.**- Read existing AGENTS.md files in scope and nearest parent/child scopes when relevant.\n- Read README/package/Cargo/build files only enough to find non-obvious commands, boundaries, and hazards.\n- Use targeted search for repeated patterns instead of copying repo documentation.\n\n-\n**Classify useful content.**- Keep rules that change agent behaviour.\n- Drop generic language, obvious stack summaries, motivational filler, duplicated docs, and stale boilerplate.\n- Preserve founder/product intent when the project is greenfield and the code cannot express it yet.\n\n-\n**Suggest before editing.**- Present proposed changes as a short list or compact draft.\n- Explain what will be removed, kept, or added.\n- Wait for user direction unless the user already asked for direct edits.\n\n-\n**Edit if approved or explicitly requested.**- Prefer editing existing AGENTS.md over creating duplicates.\n- For nested files, write only the local delta.\n- For bloated files, compress first; suggest splitting runbook/spec material into docs only when needed.\n\n-\n**Validate the result.**- Scoped, short, non-verbose, actionable.\n- No duplication of obvious codebase facts.\n- Root and nested files do not repeat each other.\n\nInclude only non-obvious deltas:\n\n- direction not encoded in code\n- non-negotiables agents might violate\n- verification exceptions, not obvious package scripts\n- architecture seams agents are likely to bypass\n- nested AGENTS / skill / doc routing\n\nTemplate:\n\n```\n# AGENTS.md\n\n- <Non-obvious project direction or current migration state>.\n- <MUST/SHOULD non-negotiable agents are likely to violate>.\n- <Verification exception: command, when to run, or what not to run>.\n- <Architecture seam: use X, do not bypass Y>.\n- <Nested AGENTS / skill / doc routing if relevant>.\n```\n\nUse for local edge cases:\n\n- folder ownership\n- import/public API boundary\n- generated/frozen/stable area rules\n- platform/tool wrappers\n- “do not put X here” traps\n- “load X skill/doc first” pointers\n\nTemplate:\n\n```\n# <Folder/module> rules\n\n- This folder owns <specific responsibility>.\n- Public access goes through <path/import/API>.\n- Keep internal imports/changes inside <boundary>.\n- Do not put <wrong concern> here.\n- Load/read <skill/doc> before changing <area>.\n```\n\nCan be prose. A founder/developer braindump is valid when it carries mission, product taste, anti-goals, and direction that the codebase cannot contain yet. Generic corporate inspiration is not useful.\n\nTemplate:\n\n```\n# AGENTS.md\n\nThis project is early. <Mission / product taste / what this should become>.\n\n- Optimize for <goal> over <non-goal>.\n- Avoid <premature complexity> until repeated patterns appear.\n- <What “good” feels like>.\n- <What not to waste time on yet>.\n- <Known starting paths, if any>.\n```\n\nCan be longer. It may include communication style, permission boundaries, memory, collaboration preferences, and identity. Do not copy personal guidance into project repos.\n\nTemplate:\n\n```\n# Personal agent guidance\n\n## Communication\n- <How to answer this user.>\n\n## Workflow\n- <How to plan, ask, commit, finish.>\n\n## Boundaries\n- <What requires explicit approval.>\n\n## Memory / continuity\n- <What to remember and where.>\n```\n\n- Nested local file: 1–10 lines.\n- Normal repo/brownfield root: up to ~20 lines.\n- Greenfield/founder note: may be longer if it carries product intent.\n- Personal/global file: may be longer if it carries relationship and operating style.\n- Over ~40 lines for a normal repo: suspicious; trim hard.\n- Over ~100 lines: probably docs/spec/runbook content.\n\n- Delete stack facts already visible in package/config files.\n- Replace paragraphs with direct bullets.\n- Replace “always be careful” with the specific forbidden action.\n- Replace copied docs with a pointer plus the decision rule.\n- Move local edge cases into nested AGENTS.md.\n- Keep RFC2119 caps only for true non-negotiables.\n\nScore out of 20:\n\n- Local specificity / 5 — unique to this repo/folder/person.\n- Actionability / 5 — commands, paths, boundaries, forbidden moves, or clear intent.\n- Non-verbosity / 4 — compact rules; no prose unless prose carries intent.\n- Source-of-truth hygiene / 3 — links or points instead of duplicating docs/code.\n- Scope fit / 3 — repo, nested, greenfield, brownfield, or personal style matches the file.\n\nFor audits or suggestions, return:\n\n- score or quality signal\n- what to keep\n- what to remove/compress\n- proposed replacement or bullet-level diff\n- questions only where user intent is genuinely needed\n\nFor edits, return:\n\n- changed path(s)\n- brief summary of what changed\n- any follow-up decisions left to the user", "url": "https://wpnews.pro/news/agents-md-authoring-skill", "canonical_source": "https://gist.github.com/IgorWarzocha/42ed1836aace7c44eb127f6194905820", "published_at": "2026-06-04 17:36:04+00:00", "updated_at": "2026-06-05 03:14:13.621923+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools"], "entities": ["AGENTS.md"], "alternates": {"html": "https://wpnews.pro/news/agents-md-authoring-skill", "markdown": "https://wpnews.pro/news/agents-md-authoring-skill.md", "text": "https://wpnews.pro/news/agents-md-authoring-skill.txt", "jsonld": "https://wpnews.pro/news/agents-md-authoring-skill.jsonld"}}