/agent-config

name: agent-config
description: "Create, update, or audit AGENTS.md (default) or CLAUDE.md agent instructions: set up, prune, add a rule, or merge CLAUDE.md or .cursorrules into one file Claude Code, Codex, and Cursor all read. Don't use for READMEs, skills, or subagents."
license: MIT
effort: medium
metadata:
  version: 2.2.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

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.