neumie Audit Agent Instruction Files
Audit a CLAUDE.md or AGENTS.md file. Score it 0-100 across six metrics, cite specific issues, suggest improvements. Each run is a standalone snapshot — user makes changes, re-runs for updated score.
Input: Path to target file. Default: ./CLAUDE.md
Scope rule: Content belongs where its domain lives. A subdirectory CLAUDE.md owns domain-specific instructions (hooks, registries, patterns used in that directory). If root also documents the same thing, recommend removing it from root entirely — not shortening, not summarizing, removing. Never suggest removing domain-specific content from a subdirectory file or deferring to root.
Debt rule: CLAUDE.md sets the rules. Existing violations don't invalidate rules. Never suggest weakening a rule, adding debt counts ("121 instances are legacy"), or qualifying with "except for existing code." However, DO suggest warning agents away from prominent bad examples they'll encounter: "Legacy pages like X predate registries — don't copy that pattern." That's a gotcha, not a debt acknowledgement.
Phase 1: Context Scan
Run before scoring. Build a mental model of what the directory actually does.
- Directory scan —
findthe directory tree. Note file types, structure, entry points, configs. - Parent CLAUDE.md scan — read all CLAUDE.md/AGENTS.md files in parent directories up to repo root. These establish context the audited file should complement, not duplicate.
- Dependency trace — grep for imports/requires referencing paths outside the directory. Map shared utilities.
- Code signals — non-obvious patterns, complex configs, multiple entry points. For subdirectory files, also scan for
// HACK,// TODO,// FIXME. For root files, skip file-level comments. - Deep module detection — identify shared abstractions: registries, contexts, factories, facades. Candidates for mandatory-use rules.
- Mental model — what does this directory do? What would trip someone up? What deep modules must agents use and extend?
File-only fallback: No codebase available → skip this phase, score on textual quality only, note in output.
Phase 2: Score Against Rubrics
Use the context scan as ground truth. See ~/.claude/skills/almanac/agents-md-audit/references/best-practices.md for detailed writing guidance.
Signal-to-Noise (25 pts)
| Range | Descriptor |
|---|---|
| 21-25 | Every line prevents a mistake or saves significant exploration time. No catalogs, no type docs, no restating what code already says. |
| 14-20 | Mostly high-value. A few lines derivable from code. |
| 7-13 | Mixed — useful rules buried among file listings or generic descriptions. |
| 0-6 | Dominated by discoverable content — directory trees, component lists, type definitions. |
Cross-references between CLAUDE.md files ("see also pages/CLAUDE.md") are noise — agents discover them by directory traversal. Each file stands on its own. Never suggest adding cross-references. Flag existing ones for removal.
Prescriptiveness (20 pts)
| Range | Descriptor |
|---|---|
| 17-20 | Commands: "use X not Y", "never do Z." Concrete wrong/right examples. Copy-paste ready. Deep modules enforced imperatively. |
| 11-16 | Mostly prescriptive. Some descriptive passages. Deep modules mentioned but not enforced. |
| 5-10 | Descriptive tone dominates — explains how things work rather than what to do. |
| 0-4 | Reads like documentation/tutorial. |
Danger Coverage (20 pts)
| Range | Descriptor |
|---|---|
| 17-20 | Documents gotchas and "compiles but breaks" scenarios. Deep modules enforced as mandatory with "always/never" — both using and extending them. Decision framework for new code. Surfaces unmentioned abstractions from scan. |
| 11-16 | Some gotchas. Some deep modules mentioned but not all enforced. No decision framework. |
| 5-10 | Few warnings. Flat catalogs ("we have X service") rather than enforced patterns. |
| 0-4 | No gotchas, no pitfalls, no architectural enforcement. |
Deep modules: check that agents are told to use existing abstractions AND extend them (add to the registry/config, don't create parallel mechanisms). "Prefer" is too weak — "always/never" is the bar.
Self-maintenance (root files only): does the file tell agents to update CLAUDE.md when they encounter undocumented gotchas or patterns? A root CLAUDE.md that doesn't ask to be maintained will go stale.
Structure & Organization (15 pts)
| Range | Descriptor |
|---|---|
| 13-15 | Clear hierarchy. Root covers project-wide, subdirectory files add scope-specific info. Scannable headers. |
| 8-12 | Reasonable. Minor issues — sections too long, slight overlap. |
| 4-7 | Flat wall of text or illogical grouping. |
| 0-3 | No structure. |
Flag root sections scoped to a subdirectory for extraction. Apply the scope rule (above) when evaluating duplication between root and subdirectory files.
Position check: Is this CLAUDE.md at the right level? Content about a specific subdirectory should be pushed down. Project-wide rules in a nested file should be pulled up to root. Content describing code that no longer lives here means the file is orphaned or misplaced.
Conciseness (10 pts)
| Range | Descriptor |
|---|---|
| 9-10 | Dense. Every sentence carries weight. Rules lead, explanations follow briefly. |
| 6-8 | Mostly tight. A few verbose passages. |
| 3-5 | Wordy. Explanations longer than the rules they support. |
| 0-2 | Bloated. Could cut 50%+ without losing information. |
Freshness (10 pts)
| Range | Descriptor |
|---|---|
| 9-10 | Everything reflects current state. No aspirational content, no stale references. Documented paths/commands verified to exist. |
| 6-8 | Mostly current. Minor drift. |
| 3-5 | Several aspirational or stale entries. |
| 0-2 | Significantly out of date. |
Phase 3: Output
## Audit: <path/to/file>
**Total: <N>/100** — <One-sentence verdict.>
| Metric | Score |
|---------------------|-------|
| Signal-to-noise | __/25 |
| Prescriptiveness | __/20 |
| Danger coverage | __/20 |
| Structure | __/15 |
| Conciseness | __/10 |
| Freshness | __/10 |
## Suggestions
### <Metric name>
- <Line N or file path>: <issue> — <concrete fix.>
Re-run to check updated score.
Cite line numbers for .md issues, file paths for codebase findings. Group by metric, skip metrics with no suggestions. Every suggestion must be actionable.