agent-config

When to Use

Create, update, or audit the instruction files coding agents load every session. AGENTS.md is the default output: it's the open standard that Claude Code (v2.1.277+), Codex, Cursor, Copilot, and others read. Produce CLAUDE.md as the output only on an explicit request, meaning the user asks for a CLAUDE.md to be written or edited ("create a CLAUDE.md", "add X to CLAUDE.md"). Naming it as a source doesn't count ("migrate our CLAUDE.md to AGENTS.md"), and neither does a CLAUDE.md that already exists on disk. Skip READMEs and contributor docs, skills (skill-creator), and subagent files under .claude/agents/.

Core Principle

These files are context, not enforced configuration. They load every session, and the agent may still deviate from them.

• Short, always-on facts the agent cannot infer go in the file.
• Multi-step procedures go in a skill. Anything that must never happen goes in a PreToolUse hook plus permissions. Verification of the work goes in tests or CI.
• Minimal beats complete. Agents run every command the file lists and obey every rule, so each extra line costs steps and tokens on every task. LLM-generated files that restate the repo measured about 20% more cost with no success gain. This skill is an LLM writing such a file, so the prune pass in Step 3 is mandatory for new content.

Which layer owns an instruction: references/knowledge-routing.md. Loading rules and sources: references/official-standards.md.

Prerequisites

• A git repo with origin set, for anything that writes. audit only needs read access.
• Tools: git, and write access to the target path.

Mode Selector

$ARGUMENTS

• audit: the user says audit, "review", or "check". Read-only.
• write: anything else (create, update, a specific change, or a path such as packages/api/AGENTS.md).

Every mode runs Step 1 first. After Step 1, a write run is a targeted edit when the user named a specific change to an existing file. Otherwise it's a full pass. Write runs continue with Steps 2–4; audit jumps to Audit.

Repo Sync Before Edits (mandatory)

Before a write run changes anything, sync with the remote. audit skips this. git fetch is the read-only dry run.

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin                       # dry-run: read-only preview
git status                             # validate clean tree
git pull --rebase origin "$branch"     # only once the tree is clean

If the tree is dirty, back it up with git stash push -u -m "pre-sync-backup", sync, then run git stash pop. Stop and ask the user to confirm whether to skip the sync if any of these happen: the directory isn't a git repo, origin is missing, the HEAD is detached, the branch has no upstream, the pull or rebase fails, or the pop fails. If the user does not authorise skipping the sync, write nothing and end with the final report as BLOCKED. Never overwrite an existing agent file without reading it and showing a diff.

Step 1: Resolve the target (every mode)

1. The output is AGENTS.md in the repo root, or the path the user gave. It's CLAUDE.md only on an explicit request (see When to Use).

2. Shadow check. By default, Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the launch directory or any directory above it; ~/.claude/CLAUDE.md doesn't count. A subdirectory's AGENTS.md loads only when that directory has no CLAUDE file of its own. Any file that counts shadows AGENTS.md. From the repo root, list CLAUDE files above the root and inside the repo:

   root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; d="$(dirname "$root")"
   while :; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do p="$d/$f"
     { [ -e "$p" ] || [ -L "$p" ]; } && [ "$p" != "$HOME/.claude/CLAUDE.md" ] && echo "ABOVE-REPO $(ls -l "$p")"
   done; [ "$d" = / ] && break; d="$(dirname "$d")"; done
   find "$root" \( -name node_modules -o -name .git \) -prune -o \( -name CLAUDE.md -o -name CLAUDE.local.md -o -name AGENTS.md \) -print |
     while read -r p; do ls -l "$p"; grep -qE '^@(\.\.?/)*AGENTS\.md' "$p" 2>/dev/null && echo "  -> imports AGENTS.md" || true; done
   

3. Classify every CLAUDE file found. Each gets its own action:

File	Action
Above the repo root (for example ~/CLAUDE.md)	Never edit it. Warn that it blocks AGENTS.md in every repo below it, and suggest moving its content to ~/.claude/CLAUDE.md, which doesn't count
CLAUDE.local.md	Never edit it. Warn that it stops Claude from reading AGENTS.md for its owner. Suggest @AGENTS.md as its first line, or /config → Project instructions → claude-md-and-agents-md. That setting is per-user and ignored in project settings
A symlink to AGENTS.md	Nothing to do. Write to the link's target, because Edit and Write refuse to write through symlinks
Already imports AGENTS.md	Keep it, holding only Claude-only lines
In the repo, no import	Migrate: move shared rules to AGENTS.md, and shrink the file to the import plus its Claude-only lines. Import paths are relative to the file, so .claude/CLAUDE.md uses @../AGENTS.md

4. Pick the branch:
   • wrapper: the user asked for both files.
   • claude-only: an explicit CLAUDE.md request and no AGENTS.md.
   • wrapper: an explicit CLAUDE.md request, and AGENTS.md exists. Write the CLAUDE.md as the import plus Claude-only lines, and touch AGENTS.md only if asked.
   • migrate: any in-repo CLAUDE file needs migrating.
   • agents-only: everything else.

Claude-only lines name Claude Code features: plan mode, /commands, skills, hooks, subagents, or MCP tools. They stay in a CLAUDE file that already exists or was requested. Otherwise they go to .claude/rules/<topic>.md, which loads alongside AGENTS.md without shadowing it. Never create a CLAUDE.md just to hold them.

When the user reports that AGENTS.md isn't loading and the shadow check is clean, check the environment before rewriting any content: claude --version (v2.1.277+), the Project instructions value in /config, and whether the agents-md plugin is enabled (official-standards.md → Claude Code).

Done when the output path(s), the branch, each CLAUDE file's action, and the raw shadow-check output are shown.

Step 2: Analyze the project (full pass)

Collect only what an agent would otherwise get wrong:

• Commands from manifests and CI (package.json scripts, pyproject.toml, Makefile, .github/workflows/*): install, dev, test all and one, lint, and typecheck, with the flags CI uses.
• Pins: the package manager and runtime version, wherever a guess would fail (pnpm, not npm).
• Boundaries: generated, vendored, and secret paths, and actions that need a human first.
• Existing rules in agent files, .cursor/rules/, .cursorrules, and .github/copilot-instructions.md. Keep what is still true, and leave those files in place.

Done when every command you will write was read from a file. If no manifest or CI defines a command, write none for it and ask the user; never guess one.

Step 3: Draft

For a targeted edit, make the requested change, add the token-efficiency block if it's missing, and change nothing else. A request for general workflow, coding-discipline, or unit-test rules is met by the matching block in references/optional-blocks.md. List other prune candidates in the report, but don't apply them. For a full pass, read references/agents-md-writing.md first. It holds the template, the writing rules, and the evidence behind them. Then:

1. Fill the template. Commands, Constraints (Never and Ask first), and Done when are required. Project, Layout, Conventions, and Read when needed appear only when they hold a fact the agent cannot infer.
2. Prune pass. Delete every line that fails the deletion test: "would removing this cause a specific mistake?" Also delete any overview, directory tree, dependency list, or restatement of the README. Keep opt-in blocks already in the file. Move Claude-only lines to the place Step 1 names.
3. Add opt-in blocks from references/optional-blocks.md (workflow orchestration, coding discipline, unit tests) only when the user asks for them.
4. Append the token-efficiency block (see below) last.

Done when every remaining line is a command, a pin, a constraint, or a pointer.

Step 4: Write and verify

• Show before writing. For a new file, show the draft. For an existing file, show the diff. Write once the user approves, or right away if the request already said to apply the change. If the user declines, write nothing and end with the final report as BLOCKED.
• Verify. If a check fails, fix the file and re-run that check once. If it still fails, end Step 4 with Result: FAIL and name the check:
  • wc -l is under 200 for each file.
  • grep -c '^## Token Efficiency' returns 1 in the source of truth and 0 everywhere else.
  • Each wrapper's first line is the AGENTS.md import.
  • Re-running the shadow check shows no in-repo CLAUDE file shadowing AGENTS.md.
• Report how to confirm the load. In Claude Code v2.1.280+, /memory lists AGENTS.md. In Codex, run codex --ask-for-approval never "Summarize the current instructions.". Clients that cannot read AGENTS.md need a one-line CLAUDE.md holding @AGENTS.md: Claude Code before v2.1.277, and some Bedrock or telemetry-off sessions before v2.1.281. Offer that file, but don't create it unasked.

Audit (read-only)

1. Read these together, because shadowing and drift only show up across the set:
   • AGENTS.md
   • every file the shadow check found
   • any AGENTS.override.md
   • .claude/settings.json and .claude/settings.local.json, for hooks
2. Walk references/agents-md-checklist.md, and report every item as pass, fail, or N/A with a one-line reason. Its loading section catches CLAUDE files that shadow without importing, prose telling Claude to "read AGENTS.md", a SessionStart hook that prints AGENTS.md, and an AGENTS.override.md that Codex reads instead.
3. Cross-check references/anti-patterns.md.
4. Route and enforce. For every failing line, name its home from references/knowledge-routing.md. A rule a machine can check gets its gate and loses its prose.
5. Modify nothing; git status must be unchanged. Give the overall verdict (PASS, PARTIAL, or FAIL) as the audit report's Result: line. Suggest /memory to see what loaded, and /doctor prompt-audit (v2.1.283+) for a second pass.

Token Efficiency Block (always inject)

Append the fenced block from references/token-efficiency-block.md once, as the last section of the source-of-truth file. The source of truth is the root AGENTS.md, or CLAUDE.md on the claude-only branch. Never add the block to a wrapper, a nested package file, or a .claude/rules/ file: those load alongside the root file, and a second copy would double it. It is the only general advice added without a request: these are always-on rules for how the agent spends its context window. Non-negotiable: add it on every write run where the source of truth lacks it, including a targeted edit, and say so in the report. The one exception is the wrapper branch: don't edit an AGENTS.md that already exists just to add the block; report that it's missing instead.

Step Completion Reports

After each step, output:

◆ [Step Name] ([step N of M])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Use √ for pass and × for fail. Adapt the check names to each step.

Final Report

End every run, including one that stops early, with the final report from references/final-report.md: Result: first (COMPLETE, PARTIAL, or BLOCKED), then Evidence:, Uncertainty:, and Decision:. The reference defines each status and holds the reader checks.

Acceptance Criteria

• The branch, each CLAUDE file's action, and the shadow-check output are shown.
• Without an explicit CLAUDE.md request, no new CLAUDE.md was created.
• After the run, every in-repo CLAUDE file either imports AGENTS.md or is a symlink to it. Files above the repo and CLAUDE.local.md were left unedited, and the user was warned about them.
• The repo was synced, or the user explicitly authorised skipping the sync.
• The token-efficiency block appears exactly once, in the source of truth, unless the wrapper branch reported it missing.
• The source-of-truth file is under 200 lines and passes sections 1–3 and 5–7 of references/agents-md-checklist.md. Wrappers and rules files pass sections 1–3 and 6.
• No rule appears in both AGENTS.md and a CLAUDE file.
• New content has no anti-pattern from references/anti-patterns.md.
• A write run that wrote files ends Step 4 with Result: PASS. Audit runs report every checklist item, give each failing line a routing recommendation, leave git status unchanged, and give the overall verdict.
• Every run ends with the final report, and it passes the reader checks in references/final-report.md. Without user feedback, human understanding of the report stays unconfirmed.

Expected Output

Branch	Files after the run
agents-only	AGENTS.md: Commands, Constraints, Done when, any optional sections, then ## Token Efficiency
migrate / wrapper	AGENTS.md as above, plus each CLAUDE file reduced to the @AGENTS.md import and its Claude-only lines
claude-only	CLAUDE.md with the full content and the token block
audit	no writes; a checklist report with routing and a Result: PASS, PARTIAL, or FAIL verdict

Every branch then prints the final report. A sample file is in references/agents-md-writing.md, a sample audit report is in references/agents-md-checklist.md, and sample final reports are in references/final-report.md.

Edge Cases

• Monorepo: prefer one AGENTS.md per package over a growing root file. Codex and most agents give priority to the closest file. Claude reads the root file plus each subdirectory's file on demand, and a CLAUDE file shadows the AGENTS.md in its own directory. Ask which scope to edit.
• A CLAUDE file that tells Claude in prose to read AGENTS.md, or holds a pasted copy of it (from /init or /import): it lacks the import, so migrate it.
• A request for AGENTS.override.md or AGENTS.local.md: Codex reads AGENTS.override.md instead of that directory's AGENTS.md, and Claude reads neither. Say so before writing one.
• Personal files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md): audit and propose only. Never rewrite a personal file from a repo-scoped run.
• A multi-step procedure: don't inline it. Propose a skill, and leave a one-line pointer.
• A draft over 200 lines: path-scope rules, extract procedures to a skill, or link out before writing.