agents-md
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.
OutlineDriven · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add OutlineDriven/odin-claude-plugin --skill agents-mdAbout this skill
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.
-
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 | sortAlso 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, anddocs/. 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.
-
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.
-
Setup: decide which files exist and which tool reads each.
AGENTS.mdat 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.mdas a symlink only when a tool in use reads solelyCLAUDE.md; a symlink keeps one source of truth where a copy would drift. Use.claude/settings.jsonfor hooks andCLAUDE.local.md(gitignored) for personal overrides. - Codex: nothing beyond AGENTS.md.
- Cursor: AGENTS.md covers prose. Add
.cursor/rules/*.mdconly for rules needing Cursor glob scoping. Frontmatter is required;alwaysApply: truewith emptyglobsduplicates 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:
@importis Claude Code only. Codex and Cursor ignore@importlines 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@importfor depth only Claude Code needs, never for safety, data-loss, or format-contract rules.@importchains stop resolving at 5 hops; deeper content silently disappears.@importlines 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, Cursorhooks.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.
-
Audit: score each root file independently. Exclude N/A checks from the denominator.
- **Qu