Content
88%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a well-structured, highly actionable audit procedure: concrete evidence sources, a per-ADR checklist, named finding categories, a report template, and gated fix steps with verification. Weaknesses are minor — some duplication between Ground Rules and later sections, and all detail inlined in one file rather than split across references.
Suggestions
De-duplicate Ground Rules against later sections: 'Read `docs/adr/INDEX.md` first' and the propose-only rule are each stated twice (Ground Rules vs. Full ADR Audit step 1 and Applying Fixes).
Consider moving the detailed Evidence Sources list and/or Finding Categories into a reference file (e.g. references/evidence-sources.md) so SKILL.md stays a lean overview, since the body currently runs ~117 lines with no bundle files.
In Applying Fixes, make the verification a closed feedback loop: specify that if a link check or grep check fails, fix the reference and re-run until it passes (currently 'run targeted verification' names the check but not the retry behavior).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and directive with no explanations of concepts Claude already knows, but it contains minor trimmable duplication — 'Read `docs/adr/INDEX.md` first' in Ground Rules is restated as audit step 1, and the propose-only rule appears in both Ground Rules and Applying Fixes. This fits 'efficient; minor instances that could be trimmed' rather than the fully lean level-5 anchor. | 4 / 5 |
Actionability | As an instruction-only skill, guidance is fully concrete: specific file paths (docs/adr/INDEX.md, docs/fdr/, AGENTS.md), an 8-point per-ADR checklist, eight named finding categories, a copy-paste markdown report template, and numbered fix steps with verification commands. Nothing is vague or pseudocode-like, so it exceeds the level-4 anchor. | 5 / 5 |
Workflow Clarity | Both workflows are clearly sequenced (audit steps 1–7, fix steps 1–6) with explicit checkpoints: a user-approval gate before any edits, a cross-reference sweep, and targeted verification ('markdown link checks or focused grep checks'), plus a per-ADR checklist. Edits are validated, so the batch/destructive cap does not apply. | 5 / 5 |
Progressive Disclosure | No bundle files exist and the 117-line body is well organized into clearly headed sections with no nested references, but everything is inlined in a single file — the detailed Evidence Sources list and What To Check checklist could live in reference files to keep SKILL.md a leaner overview. Good structure with minor organization gaps fits level 4, and the under-50-line exception for scoring 5 does not apply. | 4 / 5 |
Total | 18 / 20 Passed |