Agents md audit

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.

1. Directory scan — find the directory tree. Note file types, structure, entry points, configs.
2. 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.
3. Dependency trace — grep for imports/requires referencing paths outside the directory. Map shared utilities.
4. 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.
5. Deep module detection — identify shared abstractions: registries, contexts, factories, facades. Candidates for mandatory-use rules.
6. 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.