/agents-md

name: agents-md
description: 'Use when a repo needs agent setup, AGENTS.md added or made lean, CLAUDE.md audited, or agent instructions scored or pruned. Not for remote, credential, publish, deploy, or irreversible changes.'

Agents MD

Contract

| Field | Bound contract | |---|---| | Trigger | User asks to set up a repo for agents, add AGENTS.md, audit CLAUDE.md, make a repo agent-friendly, score agent instructions, prune long/generic/stale instructions, or produce a lean pointer-only AGENTS.md | | Authority | Reversible local: writes only AGENTS.md, CLAUDE.md (or a symlink to AGENTS.md when a target tool reads solely CLAUDE.md), CLAUDE.local.md, `.claude/settings.json`, `.cursor/rules/*.mdc`, Cursor `hooks.json`, and supporting instruction files after user confirmation; rollback is restoring the pre-edit snapshot. No remote mutation. | | Side effect | Local write to agent instruction files in the repo; no remote, credential, paid, published, deployed, or VCS mutation | | Done | Repo has working, scored, non-contradictory AGENTS.md for every target tool, plus a CLAUDE.md only when a target tool reads solely CLAUDE.md; every surviving line passes the three-check admission gate (non-discoverable, operationally significant, actionable); lean variants stay under 100 lines with pointer-only sections |

Inputs

• Required: the repository root path to audit or set up.
• Optional: target tool set (defaults to Claude Code, Codex, and Cursor); audit mode (quick or full, defaults to quick); target grade (defaults to 10/12 for quick, A for full); target file path (defaults to root AGENTS.md, then CLAUDE.md if AGENTS.md absent); scope limit (root-only versus hierarchical); owner name for the lean commit attribution line.

Procedure

AGENTS.md files are execution contracts, not knowledge bases. Every line must help an agent execute correctly with minimal context. AGENTS.md is temporary guidance, not permanent configuration: when a recurring issue has a fixable root cause in code or tooling (a lint rule, test, script, or structural change), prefer that fix and keep only the minimum instruction needed until the root cause is solved.

1. **Discover files and survey discoverability.** Find every agent instruction file in the repo:

   find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) 2>/dev/null | sort

Also check `~/.claude/CLAUDE.md` (applies to every session). For monorepos, include workspace-level files. Audit each level independently: root holds universal rules, child files hold directory-specific rules. Then survey source files to learn what is already discoverable: README, PROJECT.md, cursor rules (`.cursor/rules/` or `.cursorrules`), Copilot instructions (`.github/copilot-instructions.md`), GEMINI.md, CI/workflow files, package manager config, CONTRIBUTING.md, and `docs/`. Record what an agent can infer from these alone; anything discoverable need not be restated.

• Done when: every instruction file is listed and the discoverability survey records what an agent can learn without AGENTS.md.

2. **Choose a mode.**

• No agent instructions, or targeting a tool the repo is not wired for → **Setup** (Step 3), then **Writing from scratch** (Step 6), then **Audit** (Step 4).
• File exists and the question is quality → **Audit** (Step 4).
• File exists and is bloated (root over ~150 lines), stale, scored below target, long/generic/stale, or agents repeat avoidable mistakes → **Refactor** (Step 5).
• Repo has convention docs and user wants a lean pointer file → **Lean** (Step 6, lean variant).
• Done when: exactly one mode is selected and the entry step is identified.

3. **Setup: decide which files exist and which tool reads each.**

• `AGENTS.md` at the repo root is the source of truth. Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, and Zed all read it natively. Every other agent file is a pointer or tool-specific supplement, never a second copy. Two copies of a rule drift silently because nothing in the codebase contradicts either one.
• Claude Code: nothing beyond AGENTS.md. Add `CLAUDE.md -> AGENTS.md` as a symlink only when a tool in use reads solely `CLAUDE.md`; a symlink keeps one source of truth where a copy would drift. Use `.claude/settings.json` for hooks and `CLAUDE.local.md` (gitignored) for personal overrides.
• Codex: nothing beyond AGENTS.md.
• Cursor: AGENTS.md covers prose. Add `.cursor/rules/*.mdc` only for rules needing Cursor glob scoping. Frontmatter is required; `alwaysApply: true` with empty `globs` duplicates AGENTS.md.
• Check `.gitignore`: if agent config is ignored, decide per file whether it is personal (leave ignored) or repo knowledge (commit it). Do not put shared knowledge under `.claude/`; that path reads as Claude-only and is commonly gitignored.
• The import trap: `@import` is Claude Code only. Codex and Cursor ignore `@import` lines without warning, so a rule behind an import is absent from most sessions while the file looks correct. Anything every tool must obey goes inline in AGENTS.md. Reserve `@import` for depth only Claude Code needs, never for safety, data-loss, or format-contract rules. `@import` chains stop resolving at 5 hops; deeper content silently disappears. `@import` lines do not evaluate inside code spans or fenced blocks.
• Enforcement that survives tool choice: prefer, in order, a linter or formatter rule, a git hook (lefthook, husky) that fires whichever agent made the edit, a CI check, then tool-native hooks (`.claude/settings.json`, Cursor `hooks.json`). Tool-native hooks are the last rung because they cover one tool only. Move a prose rule down to an exit code whenever the check is mechanical, and delete the prose once the gate exists.
• Done when: the file-to-tool mapping is decided and every tool's read path is confirmed.

4. **Audit: score each root file independently.** Exclude N/A checks from the denominator.

• **Qu