| name | agents-md |
|---|---|
| description | How to write, audit and edit AGENTS.md files. |
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:
# AGENTS.md
- <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:
# <Folder/module> rules
- 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:
# AGENTS.md
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:
# Personal agent guidance
## 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