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.
A strong, highly actionable skill body: an unambiguous gated workflow with real validation and feedback loops, exact tool-call syntax throughout, and concrete conventions (numbering, status vocabulary, frontmatter). The weaknesses are mild: some repetition between the Non-goals section and the steps that could be trimmed, and no use of reference files to offload detail from the main document.
Suggestions
Trim the Non-goals section to only rules not already stated in Steps 0, 4, and 7 (or drop it and fold one-line reminders into the relevant steps) — the 'records, does not make', 'frozen once accepted', and 'what/why not how' rules each currently appear two to three times.
Move the ADR frontmatter template spec and the supersedes-wiring examples (Steps 2 and 7) into a references/ file (e.g. references/adr-template.md) and link to it, keeping SKILL.md as a lean overview.
Consolidate the repeated 'only-upside is marketing, not a record' metaphor (Steps 0, 5, and Non-goals) into its Step 5 home, where the both-directions consequences guidance lives.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and nearly every section delivers instruction, but it could be tightened: the Non-goals section restates rules already given in Steps 0, 4, and 7 ('Don't decide on the user's behalf', 'Don't rewrite an accepted record', 'Don't fold implementation detail'), the maxim 'records a decision; does not make one' appears in Step 0, Step 6, and Non-goals, and the marketing/press-release metaphors are used twice. This fits anchor 4 ('efficient; minor instances of over-explanation that could be trimmed') better than anchor 3, because the padding is repetition for emphasis rather than explanation of concepts Claude lacks. | 4 / 5 |
Actionability | Fully concrete and executable: exact tool invocations are given verbatim ('exec("ls -A decisions/")', 'exec("grep -rln <subsystem-keyword> decisions/")', 'write({ document: { path: "decisions/0012-...", template: "decision" } })', 'edit({ document: { path: ..., frontmatter: { status: "superseded" } } })', 'links({ kind: "backlinks", ... })', 'audit({ path: ... })'), plus a copy-ready YAML frontmatter block, filename format ('NNNN-title.md, zero-padded 4-digit'), and status vocabulary. Per the code_vs_instruction scoring note, this instruction-only skill has fully actionable, specific guidance covering the common cases. | 5 / 5 |
Workflow Clarity | Steps 0–9 are clearly sequenced with a HARD GATE at entry, an adversarial self-check pass in Step 6 ('fix what fails'), explicit audit validation in Step 8 ('returns clean... fix every finding'), and a both-directions wiring check for the supersedes chain ('Both edits land, or the chain is broken'). This matches the anchor-5 pattern of clear sequence + explicit validation + feedback loops + checkpoints; the destructive-adjacent edits (status flips on frozen records) are covered by the audit step, so the workflow cap does not apply. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the body is well-organized into clearly signaled Steps 0–9 plus Non-goals — good structure. It falls short of anchor 5 ('content appropriately split', well-signaled one-level references) because at ~180 lines some material — the full frontmatter template spec, the supersedes-wiring examples, and the per-section ADR craft guidance in Steps 3–5 — could plausibly live in a reference file to slim the always-loaded SKILL.md. It is above anchor 3 since what is inlined is cohesive process guidance, not bulk reference material dumped inline. | 4 / 5 |
Total | 18 / 20 Passed |