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 well-structured, token-efficient interview skill with genuinely concrete guidance (example utterances, explicit ADR gate, lazy file-creation rules). Its main defect is that both format sidecars it instructs the agent to use are absent from the bundle, leaving the glossary and ADR write steps unexecutable as written.
Suggestions
Ship ADR-FORMAT.md and GLOSSARY-FORMAT.md in the bundle (or inline their formats into SKILL.md) so the 'Use the format in...' instructions are actually followable.
Delete the duplicated sentence about AGENTS.md pointing at both locations — state it once in the Domain awareness section.
Add an explicit post-update verification step (e.g. re-read the touched glossary section or docs/adr/INDEX.md to confirm consistency after inline edits).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and prescriptive throughout — file paths, challenge heuristics, and a three-condition ADR gate with no explanations of concepts Claude already knows. Not 5 because the Domain awareness section states the same fact twice back-to-back ('both of them pointed at from the root AGENTS.md' followed by 'The root AGENTS.md is the agent manual, and it points at both'), and the attribution footer adds tokens that serve no runtime purpose. | 4 / 5 |
Actionability | Guidance is concrete and executable for an instruction-only skill: exact doc paths (docs/domain-glossary.md, docs/adr/INDEX.md), copy-ready challenge utterances ('Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?'), and a bolded three-part ADR test. Not 5 because the glossary/ADR write procedures defer to format files that are not in the bundle, and the INDEX.md update step ('says what is currently binding') is left implicit. | 4 / 5 |
Workflow Clarity | The session flow is clearly sequenced — interview one question at a time, explore the codebase when a question is answerable, challenge terms, update the glossary inline, offer ADRs only when all three gate conditions hold — with an explicit wait-for-feedback checkpoint and a three-condition decision gate. Not 5 because there is no verification step after inline updates (e.g. re-reading the glossary for consistency) and the order of the five 'During the session' techniques relative to each other is left open. | 4 / 5 |
Progressive Disclosure | Section structure is good and references are clearly signaled at one level deep ([ADR-FORMAT.md](./ADR-FORMAT.md), [GLOSSARY-FORMAT.md](./GLOSSARY-FORMAT.md)), but neither file — nor the cited .agents/skills/LICENSE-mattpocock-skills.md — exists in the bundle. Core instructions ('Use the format in [GLOSSARY-FORMAT.md]') point at missing files, which is a functional navigation failure beyond the 'minor organization gaps' of the 4 anchor. | 3 / 5 |
Total | 15 / 20 Passed |