Agents Md Polish — Development skill for Claude Code

agents-md-polish

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

Current scope

v0.1 only supports `AGENTS.md` and `CLAUDE.md` as project guidance files. It can install helper skills/commands for Claude Code and Codex, but it does not read, create, audit, or update other agent configuration formats such as `GEMINI.md`, `.cursorrules`, `.cursor/rules/`, `.windsurfrules`, or GitHub Copilot instruction files.

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 the explicit agent triggers:

• A /agents-md-polish slash command for Claude Code
• A $agents-md-polish skill command for Codex

It also installs the skill files those triggers load. Because this example uses `--create-agents` and `--bridge`, it can also create:

• AGENTS.md, if none exists. This is a short starter guidance file with TODOs for invariants,