claudemd-audit

claudemd-audit

Audits a CLAUDE.md file against an instruction budget.

When to invoke

When the user asks any of:

• •"audit my CLAUDE.md"
• •"is my CLAUDE.md too long"
• •"what rules can I move to hooks"
• •"what's wasting my instruction budget"
• •"classify the rules in my CLAUDE.md"

Also when refactoring or shrinking a CLAUDE.md.

How to use

The skill ships with audit.py. Run it against the user's CLAUDE.md:

python audit.py /path/to/CLAUDE.md

For JSON output:

python audit.py /path/to/CLAUDE.md --json

Then summarise the findings, focusing on:

1. total instruction line count vs total file line count
2. ratio of deterministic-eligible to probabilistic-only — high deterministic ratio means a lot of rules could move to hooks
3. specific vague lines that can be deleted with no loss
4. specific redundant lines that should be consolidated
5. the three biggest deterministic-eligible candidates worth moving to hooks first

Classifications

• •deterministic-eligible — rule that could be enforced by a hook (e.g. "never edit migrations", "always run lint before commit")
• •probabilistic-only — requires LLM judgment (e.g. "match the existing code style")
• •vague — no actionable signal (e.g. "be helpful", "write good code")
• •redundant — near-duplicate of another rule

Limitations

The classification heuristics are intentionally simple. They catch common signal patterns and miss subtler ones. Misclassifications are expected. Treat the output as a starting point for human review.

If a heuristic misfires noticeably on a given input, file the case as a TODO comment in audit.py rather than fixing the heuristic in place. The goal is repeatable signal, not perfect classification.