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:

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. 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. Move Claude-only lines to the place Step 1 names.
3. Add opt-in blocks from references/optional-blocks.md 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.