agentsmd-audit

# AGENTS.md Audit ## Overview A high-quality `AGENTS.md` (or `CLAUDE.md`) raises agent code quality by a measurable amount on real tasks. A poorly structured one is **worse than no docs at all**: the same file can lift one metric while dropping another by a comparable amount. The difference is structural, not stylistic. This skill audits a project's high-context instruction file against five patterns observed to correlate with measurable improvement, and against four known anti-patterns. Output is a per-pattern score, an anti-pattern report, and a concrete fix list — never a rewrite without user approval. ## When to Activate - A new `AGENTS.md` or `CLAUDE.md` was added or substantially edited. - The agent appears to ignore project conventions despite documentation existing. - A new model version was rolled out and behavior on the project shifted unexpectedly. - The instruction file has grown past 200 lines and feels noisy. - A user says "audit AGENTS.md", "review the CLAUDE.md", or "is our agent doc good". Do **not** use this skill to write a new instruction file from scratch. It only audits. ## What it checks ### Five high-leverage patterns | Pattern | Required signals | Failure means | |---------|------------------|---------------| | **1. Progressive disclosure** | Top-level file ≤ 150 lines; deeper material lives in references the agent loads on demand | The file is a single 500-line wall of text, blowing context budget on every task | | **2. Procedural workflows*...