Content
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured instructional skill with excellent workflow clarity and progressive disclosure. Its main weakness is the lack of concrete, copy-paste-ready examples — no sample spec skeleton, no example ADR output, no specific commands for the 'Ground' step. The writing is mostly efficient but could be tightened in places where it explains general engineering wisdom rather than providing novel, actionable instruction.
Suggestions
Add a concrete spec skeleton/template (even abbreviated) showing the expected sections with placeholder content, so Claude can copy-paste and fill in rather than reconstructing from prose descriptions.
Include a brief concrete example of the 'Ground' step — e.g., specific grep/read commands and what a 'Current state' section looks like when filled in.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient and well-written, but includes some sections that explain concepts Claude would already understand (e.g., what a spec is for, the general idea that you should read code before designing). The 'Your Stance' section is somewhat philosophical rather than instructional. However, most content earns its place and the failure modes section is genuinely useful. | 2 / 3 |
Actionability | The skill provides clear conceptual guidance and a structured methodology (Frame, Ground, Propose, Record), but lacks concrete executable examples — no sample spec template, no example grep commands, no example ADR output, no markdown skeleton to copy-paste. The guidance is specific in intent but abstract in execution. | 2 / 3 |
Workflow Clarity | The Four Moves provide a clear, well-sequenced workflow with explicit decision points and validation checkpoints (e.g., 'push back if code hasn't been read', 'hard-to-reverse test' before creating ADR, 'if more than a couple core questions are open, consider a spike first'). The Common Patterns section handles branching workflows well, and the Status Lifecycle provides clear state transitions. | 3 / 3 |
Progressive Disclosure | The skill provides a clear overview with well-signaled one-level-deep references to related artifacts (spec.md, adr.md, spike.md, model.md, guidelines.md). Content is appropriately scoped — the SKILL.md covers the methodology and stance while deferring schema details and per-type guides to referenced files. | 3 / 3 |
Total | 10 / 12 Passed |