Content
82%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 instruction-only skill: every section is template-driven, concrete, and free of basic-concept padding, with real validation checkpoints (one-sentence test, decision classes, success criteria) woven through. The main improvement opportunities are trimming the very long worked examples and ensuring cross-skill references resolve within the deployed bundle.
Suggestions
Move the ~70-line field.* catalog and call-site worked examples into a references/ file (e.g., references/spec-examples.md) linked from the Catalogs and Call Sites sections, tightening the main body.
Verify or make resilient the sibling-skill links (../writing-voice, ../one-sentence-test, ../pull-request/references/body-patterns.md, ../rethink/references/clean-breaks.md) — four of six cross-bundle references currently do not resolve.
Add a short explicit drafting sequence (one-sentence test -> motivation/research -> decisions -> structure -> success criteria) near the top so the workflow is a single ordered list rather than inferred from section order.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and opinionated ('A spec is in-flight scaffolding, not the durable record'; 'No process theater') and explains nothing Claude already knows, matching the score-4 anchor 'efficient; minor instances of over-explanation that could be trimmed'. The ~70-line field.* catalog example and the fully worked call-site example are longer than needed to convey the pattern, which is what keeps it from the lean score-5 anchor. | 4 / 5 |
Actionability | Guidance is fully concrete and copy-paste ready: exact naming convention 'specs/YYYYMMDDThhmmss-feature-name.md', a decision-classification table with rules, markdown templates for every section with [PLACEHOLDER] markers, and a verbatim before/after call-site pattern with file:line references. This matches the score-5 anchor 'fully executable; copy-paste ready; specific examples cover the common cases'. | 5 / 5 |
Workflow Clarity | The writing sequence is clear with most checkpoints present: apply the one-sentence-test before outlining ('If you can't name what this spec is about in one concrete sentence... the spec is not ready'), classify every material decision, record crystallized decisions as Proposed ADRs, and verify with Success Criteria checkboxes ('Tests pass / build succeeds'). It falls short of the score-5 anchor because the steps are distributed across prose sections rather than presented as one explicit ordered procedure with feedback loops for the drafting process itself. | 4 / 5 |
Progressive Disclosure | Structure is good: an up-front References section with conditional on-demand loading ('Load these on demand based on the spec's decision surface'), and the one bundle reference, references/decision-hygiene.md, exists and is one level deep with clear trigger conditions. This matches the score-4 anchor 'good structure; most content is appropriately placed; references mostly clear; minor organization gaps' — the gaps being several sibling-skill cross-references (../writing-voice/SKILL.md, ../pull-request/references/body-patterns.md, ../rethink/references/clean-breaks.md, ../../../specs/README.md) that do not resolve within this bundle, and long inline worked examples that could live in references. | 4 / 5 |
Total | 17 / 20 Passed |