Content
71%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 tight, actionable interviewing skill with concrete challenge scripts and a disciplined ADR gate, held back by a broken disclosure structure: the two referenced format sidecars are missing from the bundle entirely. Shipping GLOSSARY-FORMAT.md and ADR-FORMAT.md alongside the body would resolve its main defect.
Suggestions
Add the referenced ./GLOSSARY-FORMAT.md and ./ADR-FORMAT.md to the skill bundle (e.g., under references/) — both links in the body currently dangle, leaving the glossary and ADR entry formats unspecified.
Include the attribution-referenced .agents/skills/LICENSE-mattpocock-skills.md or trim the footer to a plain source note, so the third reference is also not a dead path.
Trim the glossary-purity passage to a single sentence (e.g., 'The glossary contains only agreed domain terms — no implementation details') and drop the duplicated AGENTS.md-authority explanation to tighten conciseness.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Efficient, prescriptive instruction with no explanations of concepts Claude already knows — the docs-layout tree and verbatim challenge phrases earn their tokens. Minor trimmable padding: 'The glossary should be totally devoid of implementation details. Do not treat it as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else' says one thing three ways, and the AGENTS.md-as-authority point is made twice. Not 5 for these small redundancies; well above 3. | 4 / 5 |
Actionability | Concrete, executable guidance throughout for an instruction-only skill: verbatim challenge scripts ('Your glossary defines "cancellation" as X, but you seem to mean Y — which is it?'), a hard three-part ADR test, lazy file-creation rules, and an explicit AGENTS.md fallback for foreign layouts. Not 5 because 'Use the format in [GLOSSARY-FORMAT.md]' and '[ADR-FORMAT.md]' point at files that do not exist in the bundle, so the entry/record formats — a key detail for the update actions — are left to improvisation. | 4 / 5 |
Workflow Clarity | The session flow is clear — explore docs first, interview one question at a time with a recommended answer per question, then condition→action pairs (conflict → call out; resolved → update inline; all three ADR criteria met → offer ADR; ambiguous context → ask, since ambiguity is itself a finding). The three-criteria gate is an explicit checkpoint. Not 5 because there is no verification step after glossary/ADR writes (e.g., re-reading the updated entry against the glossary's purity rule), a minor validation gap; the destructive/batch cap does not apply since edits are incremental single-file updates. | 4 / 5 |
Progressive Disclosure | The structure is well designed — concise session guidance inline with formats delegated to one-level-deep, clearly signaled links at the point of use — but scored against the actual bundle, both referenced sidecars (GLOSSARY-FORMAT.md, ADR-FORMAT.md) and the footer's LICENSE file are absent, so every reference dangles and the split is broken in practice. Not 4 because missing referenced files are more than a 'minor organization gap'; not 2 because the inline content is well sectioned and nothing that belongs in a sidecar is inlined. | 3 / 5 |
Total | 15 / 20 Passed |