agents-md-polish

Audit and polish AGENTS.md / CLAUDE.md guidance files for code agents (Claude Code, OpenAI Codex). Zero dependencies, Node ≥ 20.

Why short and executable?

• Anthropic recommends keeping CLAUDE.md under 200 lines: longer files "consume more context and reduce adherence." (memory docs)
• GitHub's study of 2,500 repos found auto-generated AGENTS.md files reduce task success by ~3% and inflate inference cost by 20%+.
• Claude reliably follows ~150–200 instructions per session, and Claude Code's own system prompt already takes ~50 of those. (HumanLayer)
• Splitting into @imports does not save tokens — imported files load in full at launch alongside the importer. Real reduction comes from deleting content, not reorganizing it.

Install

npm install -g agents-md-polish

Or use it without installing:

npx agents-md-polish init --tools claude,codex --yes

Use

cd your-project
agents-md-polish init --tools claude,codex --create-agents --bridge --yes

This installs:

• A reusable skill the agent loads on demand
• A /agents-md-polish slash command for Claude Code
• A starter AGENTS.md (if none exists)
• A CLAUDE.md bridge (@AGENTS.md)

Then inside Claude Code:

/agents-md-polish

Or inside Codex, just describe your intent — the skill auto-triggers on phrases like "audit my AGENTS.md", "improve our agent guidance", "make CLAUDE.md shorter":

> polish my AGENTS.md

Commands

agents-md-polish init      Install skill + slash command into a project
agents-md-polish audit     Lint an AGENTS.md / CLAUDE.md file
agents-md-polish doctor    Report installed assets in this project
agents-md-polish version
agents-md-polish help

Run agents-md-polish <command> --help for the full flag list.

Generated paths

| Tool | Path | |---|---| | Claude Code (skill) | .claude/skills/agents-md-polish/SKILL.md | | Claude Code (command) | .claude/commands/agents-md-polish.md | | OpenAI Codex (skill) | .agents/skills/agents-md-polish/SKILL.md | | Project guidance | AGENTS.md, CLAUDE.md (with --create-agents, --bridge) | | Config | .agents-md-polish/config.json |

.agents/skills/ is the cross-tool convention used by Codex, Cursor, and OpenCode. v0.1 ships skill installation for Claude Code and Codex only; adding the other tools is a v0.2 task.

Audit rules (v0.1)

Every threshold is backed either by Anthropic's published guidance or by a sample of 15 well-regarded open-source AGENTS.md files. Run with --json for machine-readable output.

| Rule | Severity | Threshold | Source | |---|---|---|---| | ROOT_LINE_COUNT | warn / error | >200 / >500 | Anthropic + p90 sample | | ROOT_BYTE_SIZE | warn / error | >12 KB / >25 KB | p75 sample + Anthropic MEMORY.md cutoff | | NESTED_SPLIT_SUGGEST | info | >400 lines or >20 KB | p90 sample | | SECTION_COUNT_H1_H2 | warn / error | >17 / >30 | p75 / p90 sample | | MAX_BULLETS_PER_SECTION | warn / error | >18 / >40 | p75 / p90 sample | | INLINE_CODE_BLOCK_LINES | warn / error | >15 / >30 | p75 sample | | CAPS_IMPERATIVE_COUNT | info | >5 | sample max=4 | | CAPS_IMPERATIVE_RATIO | warn | >10% of bullets | HumanLayer | | BROKEN_FILE_REFERENCE | error | unresolved @import or [](path) | always | | LINT_RULES_DETECTED | warn | style/format rules in AGENTS.md | HumanLayer | | VAGUE_DIRECTIVE | warn | "write clean code" etc. | blakecrosley | | AGENTS_CLAUDE_DUPLICATION | warn | Jaccard >0.5 → suggest bridge | Anthropic |

Audit exit codes: 0 ok, 1 errors, 2 missing/unreadable file.

Layered model: AGENTS.md vs Skills vs References vs Hooks vs MCP

AGENTS.md / CLAUDE.md  →  route map, invariants, commands, validation
Skills                 →  repeatable workflows loaded on demand
References             →  long docs (architecture, API specs) loaded by skill
Hooks / pre-commit     →  deterministic checks (lint, format, type)
MCP servers / CLIs     →  live external systems (GitHub, DBs, monitoring)

If a piece of guidance fits one of the lower layers, don't put it in AGENTS.md. The most common bloat sources are style rules (belongs in ESLint/Ruff/Prettier) and architecture overviews (belongs in docs/).

Development

git clone https://github.com/legendtkl/agents-md-polish
cd agents-md-polish
npm test
npm run self-audit         # lints this repo's own AGENTS.md
node bin/agents-md-polish.js init --tools claude,codex --project-dir /tmp/test --yes

Roadmap

v0.1 (current):

• Claude Code + Codex install
• 11 audit rules
• AGENTS.md / CLAUDE.md generation

v0.2 (planned):

• Cursor, OpenCode, Windsurf, Gemini, Copilot adapters
• --scope user for global-scope installs
• agents-md-polish update (smart-diff vs. just-rerun-init)
• --delivery plugin (Claude + Codex marketplace scaffolding)

License

MIT