| name | agents-md |
| description | Create, update, audit, and maintain AGENTS.md, CLAUDE.md, .cursorrules, GEMINI.md, copilot-instructions, or similar coding-agent instruction files, using evidence-based best practices. This covers setting up or bootstrapping such a file for a repo or service ("set up a CLAUDE.md", "bootstrap agent docs", "init"); cleaning up, trimming, shortening, or fixing a bloated file the agent seems to ignore; advice on what content belongs in these files; deciding between one root file vs. per-package files in a monorepo; and consolidating drifting per-tool files (Cursor, Claude Code, Codex, Copilot) into one canonical file with symlinks or imports. Also use when the user never names a file but wants coding agents to know repo-specific commands, conventions, or gotchas — they say "document this for the agent", "make sure Claude knows about X", "add this to the project instructions", the agent keeps guessing commands wrong or repeating a mistake, or a change added commands, env vars, or conventions agents must know. Handles both doing the work and answering best-practice questions about these files. |
AGENTS.md — create, update, and maintain agent instruction files
An AGENTS.md (or CLAUDE.md — same concept, different filename) is loaded into every agent session in the repo. That makes it the highest-leverage file in the project, and also the easiest to ruin: every line spends from a fixed attention budget shared by all the other lines.
The evidence (full citations in references/evidence.md):
- Frontier models reliably follow only ~150–200 simultaneous instructions, and the agent's own system prompt already consumes ~50 of those. Adherence degrades across the whole file as instruction count grows — adding a rule weakens every existing rule. The dominant failure mode is silent omission, not misinterpretation.
- A 2026 ETH Zurich/LogicStar benchmark found developer-written context files improved task success ~4%, while LLM-generated (bloated, overview-heavy) files made agents worse in 5 of 8 settings while raising cost ~20%. Codebase overviews measurably did nothing. Agents follow these files too well — anchoring on stale or irrelevant content.
- Top-performing files across a 2,500-repo corpus averaged 300–350 words. Anthropic's guidance: under 200 lines, and "bloated CLAUDE.md files cause Claude to ignore your actual instructions."
So the prime directive of this skill: the file is a budget, not a wiki. Every operation below — creating, updating, auditing — is an exercise in deciding what earns a line, not what could fill one.
The per-line litmus test
A line earns its place only if all three hold:
- Not discoverable — the agent couldn't learn it by reading the code, manifests, or lint config.
- Operationally significant — getting it wrong causes real damage or wasted work.
- Not guessable by convention — a competent agent wouldn't infer it from standard practice.
Anthropic's one-question version: "Would removing this line cause the agent to make mistakes?" If not, cut it.
What passes: build/test commands with non-obvious flags, deviations from language defaults, env vars that must be set, "legacy/ looks dead but production imports it", repo etiquette (commit format, branch rules), hard boundaries (never touch X without review).
What fails: directory maps, tech-stack overviews, file-by-file descriptions, anything a linter already enforces, standard conventions ("write tests", "use meaningful names"), detailed API docs (link instead), frequently-changing facts (they go stale and stale instructions actively misdirect).
The routing rule — not everything belongs in this file
Before adding content, route it to the right mechanism:
| Content | Destination |
|---|
| Broadly-applicable fact every session needs | AGENTS.md |
| Multi-step procedure used occasionally | A skill, or a doc linked by pointer with a one-line description |
| Rule that must hold 100% of the time | A hook or lint rule — instruction-file text is advisory, never enforced |
| Knowledge relevant to one part of the codebase | Nested AGENTS.md in that directory, or path-scoped rules |
| Something the codebase could enforce structurally | Fix the codebase (add the lint rule, delete the trap) instead of documenting around it |
When a rule keeps being violated despite being in the file, the fix is usually not more emphasis — it's either the file is too long (prune) or the rule needs to graduate to a hook.
Mode: Create (bootstrapping a new file)
- Investigate before writing. Read the package manifests and their scripts, CI config, lint/format config, Makefile/justfile, README,
.env.example, and any existing instruction files (.cursorrules, .github/copilot-instructions.md, GEMINI.md, old CLAUDE.md) whose content should be consolidated. Note the test runner, the package manager, and anything non-standard.
- Verify every command you plan to include by running it (or at minimum confirming the script exists in the manifest). A plausible-but-wrong command is worse than no command — the agent will trust it.
- Draft minimal. Use the section skeleton in
references/template.md. Resist the urge to showcase your investigation: most of what you learned is discoverable and therefore excluded. A first draft of 30–60 lines is a good sign; 200+ means you're transcribing the repo instead of distilling it.
- Set up cross-tool compatibility. Make
AGENTS.md the canonical file (it's the open standard read natively by Codex, Cursor, Copilot, Jules, Zed, and most others). For Claude Code, either symlink (ln -s AGENTS.md CLAUDE.md) or create a CLAUDE.md containing @AGENTS.md (the import form is preferred on Windows and when Claude-specific additions are needed). Details and the per-tool table are in references/template.md.
- Tell the user what you deliberately left out and why (discoverable, enforced by tooling, etc.), so they can override if they know something you don't.
If the platform's built-in generator (e.g. /init) already produced a draft, treat it as raw material to prune hard — auto-generated files are exactly the kind the ETH study measured as net-negative.
Mode: Update (the file lives alongside the code)
Update triggers — add or change a line when:
- The agent made the same mistake twice (once is noise; twice is a missing line).
- A human correction in review or chat keeps being re-typed across sessions.
- A change in this very PR adds/renames a command, env var, config schema, or architectural seam that agents must know. The instruction-file update belongs in the same PR as the change — that's the only reliable way to prevent drift.
When adding:
- Check for conflicts with existing rules first; contradictory instructions make the agent pick one arbitrarily.
- Pay for the addition: scan the file for a line that no longer earns its place and remove it. The budget is fixed; treat additions as trades.
- Place truly critical rules near the top or bottom of the file — middle-of-file instructions are the most weakly followed.
- Prefer positive framing ("Prefer X over Y because Z") over bare prohibitions ("Don't use Y") — negations are disproportionately dropped in long contexts. One short why-clause helps the agent judge edge cases; an essay spends budget. Reserve emphasis (IMPORTANT, bold) for the one or two rules that genuinely warrant it — emphasis inflation makes all of it invisible.
Mode: Audit (periodic or on request)
Run this when asked to "review/clean up the CLAUDE.md", roughly quarterly, after a model upgrade, or whenever the agent seems to ignore the file. Work through the checklist; produce a proposed diff, not just findings.
- Stale commands — for every command in the file, confirm the script/target still exists (cross-check package.json scripts, Makefile, CI). Run cheap ones to verify.
- Dead paths and pointers — every referenced file, directory, and doc must exist. A file that says
src/db/ after the code moved to src/data/ is actively harmful.
- Contradictions — rules that conflict with each other or with current code reality.
- Discoverables — content the agent would find anyway (directory layout, stack lists, things lint enforces). Cut.
- Obsolete-by-model-improvement — rules added to babysit a weaker model that current models follow unprompted. Cut, restore only on evidence.
- Emphasis inflation and vague aspirations — "write clean code"-grade lines and over-capitalization. Cut or sharpen into something verifiable.
- Length — if the file is pushing past ~200 lines or ~50 distinct instructions, propose moving procedure-shaped content to linked docs/skills and path-specific content to nested files.
- Consolidation check — duplicate instruction files for other tools (
.cursorrules, etc.) that have drifted from the canonical file.
Report the diff with a one-line justification per removal, grouped by checklist category. Removals need more justification care than additions — the user may know why a weird line exists; flag suspected-but-unverified stale lines as questions rather than silently deleting.
Monorepos
Place a lean root AGENTS.md for global defaults plus a per-package AGENTS.md for each subproject with its own toolchain. Agents use the nearest file (closest-wins, like .gitignore). Don't repeat root content in leaf files; leaf files hold only what differs. Note for Claude Code specifically: ancestor files load at launch, child-directory files load on demand when files there are read — so put always-needed content at the root and directory-specific content in the leaves.
Reference files
references/template.md — annotated section skeleton, a worked example, and the cross-tool compatibility table (which agent reads which file, symlink/import setup).references/evidence.md — the research behind every claim above, with sources. Read it when the user questions a recommendation or wants the "why".
