agent-config

When to Use

Use when the user asks to create, update, audit, or improve CLAUDE.md or AGENTS.md. Skip for generic README or contributor-doc work.

Core Principle

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

• Short, specific, always-on facts go in the file.
• Multi-step procedures go in a skill.
• "Must never happen" goes in a PreToolUse hook plus permissions.
• "Verify the work" goes in tests or CI, not a sentence.

Write the constitution here; enforce the law somewhere else. Full rules and their sources: references/official-standards.md. Which layer owns a given instruction: references/knowledge-routing.md.

Prerequisites

• Run inside a git repo with origin set; the skill requires a clean tree before destructive edits.
• Tools: git, file write access to the target path.
• Confirm whether the user wants CLAUDE.md, AGENTS.md, or both before writing.

Repo Sync Before Edits (mandatory)

Sync the current branch with remote before any create/update/delete. This is a destructive workflow — always dry-run first with git fetch (read-only) and inspect status before pulling.

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 after confirmation

If the working tree is dirty, back up via stash before syncing:

git stash push -u -m "pre-sync-backup"  # backup
git fetch origin && git pull --rebase origin "$branch"
git stash pop                            # restore

If origin is missing, rebase conflicts occur, or stash pop fails, stop and confirm with the user before continuing. Never overwrite an existing CLAUDE.md / AGENTS.md without first reading it and showing a diff.

User Input

$ARGUMENTS

Recognised inputs: create, update, audit, or a path (e.g., src/api/CLAUDE.md).

Step 1: Determine Target File

If unspecified, ask which file:

• AGENTS.md — the cross-agent source of truth, readable by any coding agent (Claude Code, Codex, others). A README for agents: setup, commands, layout, style deltas, tests, PR rules, security. Plain Markdown, no schema. Closest file wins, so nested copies override ancestors.
• CLAUDE.md — Claude-specific context loaded each conversation. When AGENTS.md already exists, CLAUDE.md opens with @AGENTS.md and carries only Claude-only extras — never a second copy of the same rules.

Default when the user says "both": write the content once into AGENTS.md, then a thin CLAUDE.md wrapper. Templates for both: references/knowledge-routing.md.

Subagent definition files (.claude/agents/*.md) are a different artifact and out of scope here — that is the subagent-creator skill's domain. Some repos, including this catalog, also keep subagent prompts inside their AGENTS.md; when the target file already uses that shape, preserve it and audit only the prose sections.

Content Guidelines (both files)

These files give the agent persistent context it cannot infer from code alone.

Size budget: under 200 lines per file (sweet spot 40–150); Codex's combined budget is 32 KiB. Past 200 lines, adherence measurably drops. When a file outgrows it: path-scope folder rules into .claude/rules/*.md, extract procedures into a skill, replace pasted docs with a pointer. Never use @import to save tokens.

Include vs Exclude

Also pin what the model would otherwise guess wrong: the package manager (pnpm, not npm), the language version, the single-test command.

See references/anti-patterns.md for the full quality test and failure modes, and references/claude-md-checklist.md for the structural audit checklist (length budget, routing, enforceability, 5 required sections, drift).

Example Format

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

# Workflow
- Typecheck after a series of code changes
- Prefer single-test runs over the full suite for performance

File Locations

• ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md — personal defaults, all sessions. The user owns these; never rewrite one from a repo-scoped run.
• ./CLAUDE.md, ./AGENTS.md — checked into git, shared with the team, reviewed like code.
• CLAUDE.local.md / AGENTS.override.md — gitignored personal overrides.
• .claude/rules/*.md with a paths: key — load only when matching files are touched.
• Nested per-package files in monorepos; closest file wins.

Imports and Emphasis

@README.md-style imports organize files but do not shrink context — imported files still load at launch. Reach for a path-scoped rule when the goal is fewer tokens.

Add IMPORTANT or YOU MUST only to true hard rules. Scattering them trains the model to ignore the markers.

AGENTS.md Guidelines

AGENTS.md is the shared, agent-agnostic contract. Use this section order:

## Project      — 2–4 sentences: what it is, invariants that must not break
## Commands     — install, dev, test (all / one), lint, types, adding a dep
## Layout       — package map, what may be edited, where tests live
## Conventions  — deltas from defaults only, one short example if needed
## Constraints  — never edit generated/, don't push to main unless asked
## Done when    — the exact lint/type/test commands that define completion
## Read when needed — pointers: billing → `docs/billing.md`

Every bullet must be a command, a pin, a constraint, or a pointer. One idea per bullet; no two bullets may contradict. Full templates, writing rules, and the maintenance feedback loop: references/knowledge-routing.md.

Token Efficiency Block (always inject)

Always append the block from references/token-efficiency-block.md once into the source-of-truth file — AGENTS.md when writing both (or when AGENTS.md already exists), otherwise the single target. Do not copy it into the CLAUDE.md wrapper; the wrapper opens with @AGENTS.md and inherits the block. This is non-negotiable — it protects the agent's context window and budget.

It is the one deliberate exception to "no general advice": these are always-on rules about how the agent works, not about the code, so the source-of-truth file is the layer that owns them.

Optional Blocks (only when requested)

If the user asks for orchestration rigor or stricter coding rules, copy verbatim the relevant block from references/optional-blocks.md (Workflow Orchestration / Mandatory Coding Discipline). Do not inject blindly.

Execution Flow

create (default)

1. Ask which file type if unspecified.
2. Analyze project: existing files, stack, README, package manifests.
3. Draft following guidelines + inject the token-efficiency block once into the source of truth.
4. If user said "apply now", write directly; otherwise present draft.
5. Finalize at the right path.

update

1. Read existing file (do not skip — used to compute diff).
2. Audit against guidelines.
3. Identify content to remove, condense, or add.
4. Apply if asked, else show diff.

audit

1. Read existing file. If both AGENTS.md and CLAUDE.md exist, read both — drift is only visible across the pair.
2. Walk every item in references/claude-md-checklist.md (length budget, content quality, routing, enforceability, 5 required sections, drift, final checks). Report each as pass / fail / N/A with a one-line reason.
3. Cross-check against references/anti-patterns.md.
4. Route and enforce. For every failing line, name where it belongs: a skill (procedure), a .claude/rules/*.md path-scoped file (folder-only), a PreToolUse hook plus permissions (must-never-happen), a test or CI (verification), or the user-level file (personal taste). A machine-checkable rule gets the gate and loses its prose.
5. Report: checklist results, anti-patterns found, routing recommendations, duplicated or contradicting rules, top recommendations.
6. Do NOT modify the file — report only. Suggest /context to confirm the file loads and /doctor to prune what the agent can infer.

Step Completion Reports

After each major 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, × for fail. Adapt check names per step.

Acceptance Criteria

A run passes when all of the following are true:

• Target file path confirmed (CLAUDE.md, AGENTS.md, or explicit path).
• Repo synced clean OR user explicitly authorised proceeding without sync.
• Token-efficiency block present in the source-of-truth file — AGENTS.md when both exist, otherwise the single target (verify by grep ## Token Efficiency). Absent from the CLAUDE.md wrapper.
• No anti-pattern from references/anti-patterns.md appears in the new content. Prose standing in for a gate is audit-time only — constitution Constraints pins do not fail create/update.
• For create / update: result passes checklist sections 1–3 and 5–7 of references/claude-md-checklist.md (length budget, content quality, routing, 5 required sections, drift, final checks). Section 4 (enforceability) is reported on audit and does not fail a create/update run.
• Generated/updated file is under 200 lines (verify with wc -l).
• No rule appears in both AGENTS.md and CLAUDE.md; when both exist, CLAUDE.md opens with @AGENTS.md.
• For audit: every checklist item is reported with pass / fail / N/A, each failing line carries a routing recommendation, and no file was modified (verify with git diff --stat).
• Final step-completion report emitted with Result: PASS.

Expected Output

For create / update: writes the chosen target; when the user said "both", writes two files (AGENTS.md plus a thin CLAUDE.md wrapper that opens with @AGENTS.md and does not copy the token block). Example tail of the source-of-truth file:

## Token Efficiency
- Never re-read files you just wrote or edited. You know the contents.
- Never re-run commands to "verify" unless the outcome was uncertain.
... (rest of token-efficiency block)

Followed by a step-completion report ending in Result: PASS.

For audit: prints a markdown report (no file writes) covering every checklist section, e.g.:

◆ Audit (step 1 of 1)
  Length budget:      √ pass — 64 lines
  Content quality:    × fail — 3 fluff lines ("be a senior engineer", motivational)
  Routing:            × fail — 12-line deploy runbook belongs in a skill
  Enforceability:     × fail — "never commit .env" has no PreToolUse hook
  5 required sections: × fail — missing "Constraints" and "Done when"
  Drift:              × fail — 2 rules duplicated in AGENTS.md
  Anti-patterns:      × fail — found 2 (generic style rules)
  Token block:        × fail — missing
  Result:             PARTIAL

Edge Cases

• No existing CLAUDE.md and update requested → fall back to create, confirm with user first.
• Both root and child CLAUDE.md exist → ask which scope to edit; never silently overwrite both.
• Dirty working tree → stash backup before sync; if stash pop conflicts, stop and ask.
• Missing origin → skip sync, warn user, require explicit confirmation to proceed.
• User pastes raw $ARGUMENTS with no recognised verb → ask which mode (create/update/audit).
• AGENTS.md already exists and user asks for CLAUDE.md → write the wrapper (@AGENTS.md + Claude-only extras), never a duplicate of the shared rules.
• Target is a personal file (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) → audit and propose only; never rewrite a user's personal file from a repo-scoped run.
• Monorepo → propose nested per-package files rather than growing the root file.
• Requested content is a multi-step procedure → decline to inline it; propose a skill and leave a one-line pointer.
• Generated file would exceed 200 lines → reject; path-scope, extract to a skill, or link out instead.

Anti-Patterns to Avoid

See references/anti-patterns.md for the full list (style rules linters cover, generic advice, file-by-file dumps, etc.).