Content
70%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.
The skill lays out an unusually rigorous, well-gated workflow with explicit validation and feedback loops, written leanly for a competent reader. Its main defect is that step 7 depends on DESIGN-DOC-TEMPLATE.md, which is absent from the skill bundle, making the drafting step — the skill's core output — non-executable as written.
Suggestions
Add the missing DESIGN-DOC-TEMPLATE.md to the skill directory (or a references/ bundle file referenced from the body) so the step 7 instruction "Read DESIGN-DOC-TEMPLATE.md from this skill directory before drafting" is actually executable; alternatively inline a minimal section skeleton in the body.
Trim cross-step repetition: consolidate the "return to step 5 on unresolved material decisions" rule and the ownership/edge-case rules into single authoritative statements that later steps refer back to, as the skill itself instructs for the documents it produces.
State in the body (or the template) what the required reviewer-path sections are, so the absence of the template file would not leave the drafting step without its section structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, prescriptive, and assumes Claude's competence — no known concepts are re-taught — but there is minor restatement across steps ("If a material decision remains unresolved, return to step 5" in both steps 7 and 8, and the step 9 checklist re-lists step 4's edge-case and ownership rules) that could be trimmed. Efficient overall, so it sits above the 'some unnecessary explanation' anchor at 3 and below the every-token-earns-its-place anchor at 5. | 4 / 5 |
Actionability | Mostly concrete — an exact question format template, the quoted adversarial-reviewer prompt, the default destination "docs/design/<descriptive-slug>.md", and the command "git diff --check -- <document-path>" — but the central drafting step (step 7) instructs "Read DESIGN-DOC-TEMPLATE.md from this skill directory before drafting" and that file does not exist in the bundle, leaving the core deliverable step non-executable. A missing key detail for the skill's primary output keeps this below the 'minor gaps' anchor at 4. | 3 / 5 |
Workflow Clarity | Nine clearly sequenced steps with explicit gates and feedback loops: "Do not write the implementation plan or draft the design until this gate is complete" (step 5), reconciliation of adversarial findings with "return to step 5 and wait for confirmation" (step 8), and a final review checklist (step 9) that verifies links, commands, and unresolved blockers against the current checkout. Matches the anchor for clear sequence, explicit validation, error-recovery loops, and checklists. | 5 / 5 |
Progressive Disclosure | The body itself is well sectioned and the reference is clearly signaled ("Read DESIGN-DOC-TEMPLATE.md from this skill directory"), but no bundle file exists — there is no references/ directory and no template file — so the intended one-level-deep split does not function and all drafting structure must be improvised. Structure is good, but the broken/absent reference and monolithic inline detail place this between the 'minimal structure' anchor at 2 and the 'good structure, clear references' anchor at 4. | 3 / 5 |
Total | 15 / 20 Passed |