# Agents Md Polish

> Audit and improve AGENTS.md / CLAUDE.md guidance files. Use this skill when the user asks to audit, polish, improve, shrink, refactor, fix, lint, or optimize AGENTS.md or CLAUDE.md; when they want to convert a bulky CLAUDE.md into a short AGENTS.md plus a CLAUDE.md bridge; when they want to create a starter AGENTS.md from scratch; or when they want to understand why an agent is ignoring rules in the guidance file.

- Skill: `legendtkl/agents-md-polish` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add legendtkl/agents-md-polish`
- Raw SKILL.md: https://api.skillmd.com/api/skills/legendtkl/agents-md-polish/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: legendtkl (https://skillmd.com/u/legendtkl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/legendtkl/agents-md-polish

---


<!-- generated-by: agents-md-polish@{{version}} -->

# Agents MD Polish

A short, repeatable workflow for keeping AGENTS.md and CLAUDE.md files
**short, project-specific, and executable**. Anthropic recommends keeping
CLAUDE.md under 200 lines; longer files "consume more context and reduce
adherence." Bloated files cause agents to ignore your actual rules.

## When invoked, run this workflow

### 1. Discover

Find guidance files in the current project:

```
AGENTS.md, CLAUDE.md
```

Check the repo root first, then any nested `AGENTS.md` files in subdirectories
(monorepos use one per package, with the closest file taking precedence).

### 2. Audit

Use `references/audit-checklist.md` to score each file. The deterministic
checks (line count, byte size, broken file references) live in
`scripts/audit_agents_md.mjs` — run it first:

```
node scripts/audit_agents_md.mjs <file>
```

The script exits non-zero on broken file references or missing files. Read
its JSON output (when invoked with `--json`) to drive follow-up actions.

### 3. Diagnose

For each issue, look up the matching pattern in `references/polish-patterns.md`
and explain the *why* in one sentence. Don't dump the whole pattern — just the
1-line summary so the user understands the recommendation.

### 4. Propose

Group the proposed changes by severity (error → warn → info). For each, show
a unified diff using the Edit tool's preview format. Don't apply yet.

### 5. AWS test (sanity gate)

Before applying, ask of every line you would *keep*:

> "If I remove this line, will an agent make a mistake?"

If the answer is no, propose deletion instead of modification. Bias toward
shorter files.

### 6. Apply

Apply changes the user accepted. For long extracted content (architecture
notes, API specs, full command lists), write to `docs/<topic>.md` or
`AGENTS-references/<topic>.md` and reference from AGENTS.md by relative
path with a `file:line` pointer where possible.

### 7. Bridge-ify (if applicable)

If both AGENTS.md and CLAUDE.md exist and overlap by more than 50%, propose
collapsing CLAUDE.md to a single-line bridge:

```
@AGENTS.md
```

Use `references/claude-bridge-template.md` for the bridge pattern and the
short explanation to show the user.

Only keep Claude-specific addenda below the import line if they are *not*
useful to Codex.

## Create path (when no guidance file exists)

If the user wants a starter AGENTS.md and none exists, copy
`references/agents-md-template.md` and fill in the project-specific sections
by inspecting the repo:

- Read `package.json` / `pyproject.toml` / `Cargo.toml` for scripts and entry points
- Skim top-level directories to populate Project map
- Don't invent invariants — ask the user for 1-3 they actually care about

## What goes in AGENTS.md vs elsewhere

| Type of guidance | Where it goes |
|---|---|
| Route map, commands, invariants, validation entrypoints | AGENTS.md |
| Repeatable multi-step workflows | Skills (`.agents/skills/`, `.claude/skills/`) |
| Long architecture notes, API specs, testing guides | `docs/` referenced from AGENTS.md |
| Lint / formatter / style rules | `pre-commit`, ruff/eslint config — NOT AGENTS.md |
| Live external systems (GitHub, DBs, browser) | MCP servers / CLIs |

## Hard limits to keep in mind

- Root AGENTS.md: target <200 lines (Anthropic), warn at 200, error at 500
- Root file size: warn >12 KB, error >25 KB
- Sections (H1/H2): warn >17, error >30
- Bullets per section: warn >18
- Inline code blocks: warn >15 lines (extract to referenced file)
- Imports do **not** save tokens — Anthropic loads them in full at launch.
  The only real reduction is deleting content.