Content
56%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 highly actionable, well-validated workflow for creating spec-kit feature specifications, with explicit feedback loops and checklists. Its main weaknesses are token waste from verbatim-duplicated hook rules and repeated clarification limits, a confusing nested step numbering, and a monolithic structure that inlines templates and hook logic that belong in reference files.
Suggestions
Extract the shared hook dispatch rules (extensions.yml parsing, enabled filtering, condition handling, dot-to-hyphen conversion) into a single shared section or a references/hooks.md file and reference it from both the pre- and post-execution sections, cutting ~40 duplicated lines.
Remove the 'CRITICAL - Table Formatting' guidance explaining pipe alignment and 3-dash separators — Claude already knows markdown table syntax — and drop one of the three restatements of the max-3 [NEEDS CLARIFICATION] limit.
Move the full checklist template and the question-format template into references/ files (e.g., references/checklist-template.md, references/question-format.md) so SKILL.md stays a concise overview, and flatten the doubled step numbering by merging the nested 'execution flow' sub-steps into the outer Outline steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The hook dispatch rules (enabled-filtering, condition handling, dot-to-hyphen conversion) are repeated nearly verbatim in both the Pre-Execution Checks and Mandatory Post-Execution Hooks sections, the 'Maximum 3 [NEEDS CLARIFICATION]' rule is stated three times, the informed-guesses guidance is duplicated, and the 'CRITICAL - Table Formatting' block explains markdown table basics (pipe spacing, 3-dash separators) that Claude already knows. This matches 'noticeably verbose; several unnecessary explanations or padded sections' rather than the mostly-efficient anchor 3. | 2 / 5 |
Actionability | Provides concrete executable guidance — '.specify/scripts/bash/resolve-template.sh spec-template --json', 'mkdir -p SPECIFY_FEATURE_DIRECTORY', exact file paths, the feature.json JSON format, and full markdown templates for the checklist and clarification questions. Minor gaps keep it below 5: hook invocation is described abstractly ('run it the same way you would run the command yourself') and several steps depend on unspecified TEMPLATE_CONTENT. | 4 / 5 |
Workflow Clarity | The sequence (pre-hooks → spec creation → quality validation with a max-3-iteration fix/re-validate feedback loop → post-hooks → completion report → Done When checklist) is clear and well-checkpointed. It falls short of anchor 5 because the nested '6. Follow this execution flow' sub-steps 1-8 restate and interleave with the outer steps 1-8, creating a confusing doubled numbering. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent) and all content is inlined in a single ~335-line file with reasonable section headers. Large self-contained blocks — the duplicated hook dispatch rules, the full checklist template, and the question format template — clearly belong in separate reference files, matching anchor 3 ('some structure... content that should be separate is inline'). | 3 / 5 |
Total | 13 / 20 Passed |