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 body delivers an exceptionally clear, validated workflow with concrete commands, templates, and robust recovery protocols, and its guidance is largely executable. Its weaknesses are verbosity from duplicated role prose and long generic example sections, plus two referenced catalogs that are empty placeholders, which both undermines the MUST-read steps and argues for moving bulk examples into reference files.
Suggestions
Populate `references/experts.md` and `references/signals.md` (or drop the MUST-read mandates) — they currently contain only a heading, so the mandated steps produce no guidance.
Move the ~180-line Context Engineering example section into a reference file (e.g. `references/context-engineering.md`) and keep a short pattern summary with a one-line pointer per pattern in SKILL.md.
Merge the "Spec-Driven Development & Your Role" prose paragraph into the Guidelines bullets — they cover the same ground (ground in PRD/codebase, WHAT not HOW, temporal ordering) twice.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The Invocation Contract, Guidelines, and Output Structure are efficient and instruction-dense, but the ~340-line body carries noticeable padding: the "Spec-Driven Development & Your Role" prose paragraph substantially repeats the Guidelines bullets, and the ~180-line Context Engineering section teaches generic spec-writing patterns through invented e-commerce examples (Student/Lesson/DynamoDB) that Claude could produce unprompted. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' — not 2, since none of it is concept-explanation filler like explaining what a library is, and not 4, since the duplication and generic example bulk go beyond minor trimmable instances. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: exact invocation (`claude -p "/spec-planning <feature>"`), exact input/output paths, a numbered completion protocol with git add/commit/push steps, idempotency and crash-recovery handling, and copy-paste markdown templates for the Signal section and Slice Dependency Map. The main gap is that the two "MUST Read" catalogs (`references/experts.md`, `references/signals.md`) are effectively empty (single heading, no content), so those steps yield nothing actionable — minor gaps that keep this at 'mostly executable guidance with minor gaps' rather than fully copy-paste-ready at 5. | 4 / 5 |
Workflow Clarity | The multi-step process is explicitly sequenced (completion protocol: write artifacts → commit/push → touch sentinel → commit/push) with strong validation and feedback loops: the sentinel is gated on prior steps, idempotency short-circuits repeat invocations, crash recovery ("verify the existing artifacts are complete and self-consistent, fix any gaps, then write the sentinel") handles partial failure, and the ambiguous-PRD path (write clarifications-needed.md, exit without sentinel) is an explicit error-recovery branch. This matches the top anchor 'clear sequence with explicit validation steps; feedback loops for error recovery'. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned and its two reference files exist at one level deep, but both referenced catalogs (`references/experts.md`, `references/signals.md`) are empty placeholders containing only a heading, making the "MUST Read the experts catalog at START of planning" pointers effectively broken; meanwhile ~180 lines of Context Engineering example material that would fit naturally in a reference file are inlined in SKILL.md. This sits at 'some structure but could be better organized; references present but not clearly signaled; content that should be separate is inline' — not 2 (structure and navigation are present, not minimal/buried) and not 4 (the empty references and inlined bulk are more than minor gaps). | 3 / 5 |
Total | 15 / 20 Passed |