Agents md

AGENTS.md / CLAUDE.md authoring & improvement

You help users write agent-instruction files that actually get followed. This skill encodes hard-won research on what works; the references hold the depth. Keep this body in context and pull references in as the task demands.

The one mental model that drives every decision

An agent is a stateless function. Each session knows only the tokens fed into it. The instruction file is the onboarding payload — and it loads on every request, relevant or not. So two forces are always in tension:

• Cover the essential context the agent can't infer on its own.
• Every token is paid every turn and competes with the actual task. Past ~150–200 instructions, a frontier model's adherence degrades uniformly across all of them — a bloated file makes the agent worse at following even its good rules.

Every rule below falls out of that tension. When in doubt, ask: is this relevant to nearly every task? If not, it does not belong in the always-on body. And when two phrasings both work, the shorter one wins: conciseness isn't a stylistic nicety here, it's the core value, because the file's cost is paid on every request forever. A file half the length that keeps every load-bearing fact is strictly better.

Progressive disclosure is the main lever — and it's not just for monorepos. The root file should hold only what's relevant to nearly every session. Everything situational moves to a file that loads when it's actually needed:

• A nested AGENTS.md (with a CLAUDE.md next to it) in a specific directory loads on demand, only when the agent works in that subtree. This is the real context-saving mechanism, and any repo can use it — a single-package repo can put a file at src/db/AGENTS.md for migration rules, no monorepo required.
• A path-scoped rule (.claude/rules/*.md with paths: frontmatter) loads only when the agent touches matching files. Lazy and strong, but Claude-specific.
• A topic file (ARCHITECTURE.md, docs/TESTING.md, SETUP.sh) the agent opens when the task calls for it.

Mind the loading model — it's the thing most people get wrong: a @path import written in the root loads at launch, in full, so it saves zero tokens (it's organization, not disclosure). Real savings come from where content lives: nested files and path-scoped rules load on demand. So use @ for the always-loaded wiring (the CLAUDE.md→AGENTS.md bridge; references inside a nested file, which ride along only when that file loads); for a cross-cutting topic file you want lazy, prefer a path-scoped rule or a lightweight pointer the agent opens itself, not a root @import. Full model in references/layout.md.

AGENTS.md vs CLAUDE.md: same idea, different reader. AGENTS.md is the vendor-neutral standard (Codex, Cursor, Copilot, Aider, Jules, and 20+ tools). Claude Code reads CLAUDE.md. You don't have to choose — see references/layout.md for the symlink / reference approaches.

Step 0: Detect what exists

Before anything else, find out whether an instruction file is already present:

fd -H -i '^(AGENTS|CLAUDE)\.md$' . 2>/dev/null || find . -iname 'AGENTS.md' -o -iname 'CLAUDE.md' 2>/dev/null

• Nothing found → Authoring path (below).
• One or more found → Improving path (below). Read every one; in monorepos the nearest file to edited code wins, so they interact.

If a file exists but the user explicitly wants a fresh start, treat it as authoring but preserve any commands/gotchas worth keeping.

Step 0.5: Ground the file in real usage (highest-signal input)

Guesses about what the agent gets wrong are cheap and often wrong; the record of it actually failing in this repo is ground truth. Before drafting or auditing, mine prior agent sessions for four signal classes — tool failures (commands/edits that errored repeatedly), tool rejections (calls the user denied, often with the corrective rule typed inline), correction prompts (messages that redirected the agent), and memory files (facts already captured out-of-band). Each is a candidate line, converted to a paired don't/do or a command the file was missing.

This step is vendor-neutral in spirit, but the only readily mineable source today is Claude Code's local logs — so the mechanics are Claude Code-specific and live in references/mining-usage.md. Start by running the bundled miner (scripts/mine-usage.sh, alongside this SKILL.md — invoke it by its absolute path), which ranks all four classes by frequency:

bash <this-skill-dir>/scripts/mine-usage.sh <repo-path>

Two rules govern what you do with the output:

• Candidates, not conclusions. A row earns a line only if it recurs (the count column is the first filter) and isn't already enforced by a linter/formatter/CI.
• Project fact vs. user preference — classify every candidate. Logs are one person's sessions, so signals are entangled with that person's habits. Only repo-true facts a new teammate would need go in the committed file; personal workflow/tone preferences belong in the user's own ~/.claude/CLAUDE.md, not the shared file. The full rubric (and how to handle ambiguous cases — ask the user) is in references/mining-usage.md.

If the repo has no prior Claude Code history, skip this and rely on code exploration.

Authoring path (no file yet)

The goal is a lean, high-signal file — not a complete description of the repo. Work in this order:

1. Explore the codebase to find what isn't obvious from a glance. The agent will read the code in-context, so don't document what the code already shows. Document what surprises. Use a subagent for multi-step exploration to keep your own context clean. Full checklist: references/authoring.md. Pair this with the mined-usage signals from Step 0.5 — the failures and corrections point straight at the gotchas worth writing.

2. Sort what you found by relevance, then place it (progressive disclosure). This is the core authoring decision, and it applies to every repo, not just monorepos:

   • Relevant to nearly every session → the root file body. Keep this minimal.
   • Relevant only in one part of the repo → a nested AGENTS.md in that directory (e.g. services/api/AGENTS.md, or even src/db/AGENTS.md in a single-package repo). Loads on demand when the agent works there.
   • Situational depth (a runbook, the test harness, architecture) → a topic file (docs/TESTING.md, ARCHITECTURE.md, SETUP.sh) pointed at by a plain path so the agent opens it on demand — not a root @-import, which would load it at launch (see layout.md). A .claude/rules path-scoped rule is the lazy-but-strong Claude-only alternative.
   • The symlink/reference setup, the launch-vs-on-demand loading model, nested-file mechanics, and monorepos: references/layout.md.

3. Draft the root-file minimum — project identity (one sentence), directory/package map, tech stack (1–2 lines), package manager + the real commands (build/test/lint/format incl. the targeted "one file" form; cut only the universally-known ones). Then add situational and domain content using the patterns that measurably help: references/patterns.md.

4. Present the draft for review, explain the layout and what went into nested/topic files, and offer to write the symlink. Only ask the user when something genuinely can't be inferred (e.g. which of two plausible deploy flows is canonical).

Improving path (file already exists)

A file already exists, so the highest-leverage move is usually subtraction, not addition. Three passes — see references/improving.md for the full method and the report format:

1. Cut what doesn't earn its tokens — obvious instructions, anything the code already teaches in-context, linter/formatter style rules (cut the rules, but keep the lint/format/test commands — the agent should still run them), stale paths and snippets, vague guidance ("write clean code"), and meta-commentary about the file itself. Full list: references/anti-patterns.md.

2. Add the hidden gotchas the user hits repeatedly — the non-obvious things that aren't visible in the code (e.g. "use Decimal not float for money", an env var that must be set, a build step that looks optional but isn't). Pair every prohibition with the correct alternative. The Step 0.5 mining is the best source here: a rule that keeps getting violated despite already being in the file means the file is too long to follow or the rule is phrased weakly — shrink the payload or rewrite as a paired don't/do, don't just restate it louder.

3. Restructure for progressive disclosure — move anything not relevant to nearly every session out of the root: directory-specific rules into a nested AGENTS.md (loads on demand, works in any repo), situational depth into a topic file. Point at that topic file from the root with a plain path (see docs/TESTING.md) so the agent opens it on demand — not @docs/TESTING.md, because a root @-import loads at launch even when it's inside an <important if> (the gate narrows the prose, not the import). Reserve @ for the always-loaded bridge and for references inside a nested file. For rules that stay in the root but are situational, gate them behind <important if="..."> with narrow triggers. Keep foundational content unwrapped and near the top. The loading model is in references/layout.md; getting this right is what actually shrinks the always-on payload.

Always show the user a before/after and the reasoning, then apply with their go-ahead.

"The agent ignores my file"

This is a common entry point. The cause is almost always that the file grew large enough that the harness's "may or may not be relevant" framing led the agent to treat the whole thing as optional. The fix is the improving path: shrink the always-on core, gate the rest. Point them there.

Reference files

Read on demand — don't load everything upfront:

File	When
references/authoring.md	Exploring a codebase to write a new file — the discovery checklist and root-file minimum
references/improving.md	Auditing/improving an existing file — the 3-pass method and report format
references/patterns.md	Choosing how to express a rule — workflows, decision tables, snippets, paired don't/do, instruction budget
references/anti-patterns.md	Deciding what to cut or keep out
references/layout.md	Progressive disclosure, the launch-vs-on-demand loading model, @-references, nested files, symlink mechanics, discovery hierarchy, monorepos
references/mining-usage.md	Claude Code-specific. Mining session logs for pain points — the miner script, raw jq recipes, and the project-fact-vs-user-preference rubric