AGENTS.md authoring skill

Create 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.

• Suggest changes before editing; discuss first unless the user explicitly asks for direct edits.
• Normal repo/brownfield AGENTS.md should aim for ~20 lines or less.
• Do not restate what an agent can infer from code, package files, folder names, or a quick search.
• Prefer compressed, high-signal half-sentences over full prose, except for greenfield/founder notes and personal/global files.
• Nested AGENTS.md files should mostly contain local edge cases, local pointers, or skill/doc routing.
• Use RFC2119 caps ( MUST

,SHOULD

,REQUIRED

) sparingly for true non-negotiables. - Do not use XML-ish wrappers by default.

• Target path or repo/folder scope.
• Desired mode: audit, suggest, draft, rewrite, split, or create missing root guidance.
• Project type when known: greenfield, brownfield, nested, or personal/global.
• User intent, preferences, or comments about tone/strictness.

If the target or project type is unclear, inspect briefly and infer. Ask only when the edit direction or blast radius is ambiguous.

Scope the work.- Identify whether the target is repo-level, nested, greenfield, brownfield, or personal/global.

• Stay inside the user-requested scope. Do not wander into unrelated dependencies or archives just because they contain AGENTS.md.

Inspect only what matters.- Read existing AGENTS.md files in scope and nearest parent/child scopes when relevant.

• Read README/package/Cargo/build files only enough to find non-obvious commands, boundaries, and hazards.

• Use targeted search for repeated patterns instead of copying repo documentation.

Classify useful content.- Keep rules that change agent behaviour.

• Drop generic language, obvious stack summaries, motivational filler, duplicated docs, and stale boilerplate.

• Preserve founder/product intent when the project is greenfield and the code cannot express it yet.

Suggest before editing.- Present proposed changes as a short list or compact draft.

• Explain what will be removed, kept, or added.

• Wait for user direction unless the user already asked for direct edits.

Edit if approved or explicitly requested.- Prefer editing existing AGENTS.md over creating duplicates.

• For nested files, write only the local delta.

• For bloated files, compress first; suggest splitting runbook/spec material into docs only when needed.

Validate the result.- Scoped, short, non-verbose, actionable.

• No duplication of obvious codebase facts.
• Root and nested files do not repeat each other.

Include only non-obvious deltas:

• direction not encoded in code
• non-negotiables agents might violate
• verification exceptions, not obvious package scripts
• architecture seams agents are likely to bypass
• nested AGENTS / skill / doc routing

Template:

- <Non-obvious project direction or current migration state>.
- <MUST/SHOULD non-negotiable agents are likely to violate>.
- <Verification exception: command, when to run, or what not to run>.
- <Architecture seam: use X, do not bypass Y>.
- <Nested AGENTS / skill / doc routing if relevant>.

Use for local edge cases:

• folder ownership
• import/public API boundary
• generated/frozen/stable area rules
• platform/tool wrappers
• “do not put X here” traps
• “load X skill/doc first” pointers

Template:

- This folder owns <specific responsibility>.
- Public access goes through <path/import/API>.
- Keep internal imports/changes inside <boundary>.
- Do not put <wrong concern> here.
- Load/read <skill/doc> before changing <area>.

Can 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.

Template:

This project is early. <Mission / product taste / what this should become>.

- Optimize for <goal> over <non-goal>.
- Avoid <premature complexity> until repeated patterns appear.
- <What “good” feels like>.
- <What not to waste time on yet>.
- <Known starting paths, if any>.

Can be longer. It may include communication style, permission boundaries, memory, collaboration preferences, and identity. Do not copy personal guidance into project repos.

Template:

## Communication
- <How to answer this user.>

## Workflow
- <How to plan, ask, commit, finish.>

## Boundaries
- <What requires explicit approval.>

## Memory / continuity
- <What to remember and where.>

• Nested local file: 1–10 lines.

• Normal repo/brownfield root: up to ~20 lines.

• Greenfield/founder note: may be longer if it carries product intent.

• Personal/global file: may be longer if it carries relationship and operating style.

• Over ~40 lines for a normal repo: suspicious; trim hard.

• Over ~100 lines: probably docs/spec/runbook content.

• Delete stack facts already visible in package/config files.

• Replace paragraphs with direct bullets.

• Replace “always be careful” with the specific forbidden action.

• Replace copied docs with a pointer plus the decision rule.

• Move local edge cases into nested AGENTS.md.

• Keep RFC2119 caps only for true non-negotiables.

Score out of 20:

• Local specificity / 5 — unique to this repo/folder/person.
• Actionability / 5 — commands, paths, boundaries, forbidden moves, or clear intent.
• Non-verbosity / 4 — compact rules; no prose unless prose carries intent.
• Source-of-truth hygiene / 3 — links or points instead of duplicating docs/code.
• Scope fit / 3 — repo, nested, greenfield, brownfield, or personal style matches the file.

For audits or suggestions, return:

• score or quality signal
• what to keep
• what to remove/compress
• proposed replacement or bullet-level diff
• questions only where user intent is genuinely needed

For edits, return:

• changed path(s)
• brief summary of what changed
• any follow-up decisions left to the user