Content
78%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 well-structured workflow skill body: clear role framing, a concrete five-step process with named tools, minimal inline format examples, and an exemplary one-level-deep reference table with load conditions. Weaknesses are modest — a mirror-image MUST NOT constraint list and non-instructional footer padding, no inline scaffolding for the interview phase itself, and no explicit recovery loop when stakeholder validation fails.
Suggestions
Collapse the MUST NOT list into the MUST DO list (or keep only the non-mirrored items like "Accept vague requirements ('make it fast')" and "Skip security considerations"), since most prohibitions restate the positive constraints verbatim.
Add a brief inline example of one or two PM-Hat/Dev-Hat interview questions so the core Interview step is executable without immediately loading the reference.
State the recovery loop explicitly in the Validate step, e.g., 'If the stakeholder rejects criteria or requirements conflict, revise and re-validate before proceeding to Plan'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is fundamentally tight (tables, short sections, no explanations of concepts Claude already knows), but there is trimmable redundancy: the MUST NOT list mirrors MUST DO nearly item-for-item ("Provide testable acceptance criteria" vs "Write untestable acceptance criteria"; "Conduct thorough interview before writing spec" vs "Generate spec without conducting interview"), "When to Use This Skill" repeats the frontmatter triggers, and the maintainer/footer links add no instructional value. This fits anchor 4 (efficient with minor trimmable instances) rather than anchor 5 (every token earns its place); it is above anchor 3 because nothing explains known concepts or pads substantially. | 4 / 5 |
Actionability | Concrete guidance dominates: each workflow step names its tool ("Use `AskUserQuestions` to understand the feature goal...", "Use multi-agent discovery with Task subagents"), inline EARS syntax patterns and a full Given/When/Then example are copy-paste ready, and the output structure plus "Save as: `specs/{feature_name}.spec.md`" are specific. It sits between anchors 4 and 5: the Document and Plan phases are fully templated, but the Interview phase — the skill's core activity — is only described ("Systematic questioning from both PM and Dev perspectives") and delegated to a reference with no inline example scaffolding, a minor gap that keeps it below "specific examples cover the common cases". | 4 / 5 |
Workflow Clarity | The five numbered steps (Discover → Interview → Document → Validate → Plan) are clearly sequenced with per-step tools, an explicit validation gate ("Validate - Use `AskUserQuestions` to review acceptance criteria with stakeholder"), and a clarification loop ("Ask for clarification on ambiguous requirements"), placing it above anchor 3's missing checkpoints. It falls short of anchor 5's "feedback loops for error recovery" because no recovery path is stated for when stakeholder validation fails (e.g., revise requirements and re-review) — rejection handling is only implied. No destructive/batch operations are involved, so the workflow-clarity cap does not apply. | 4 / 5 |
Progressive Disclosure | Verified against the actual bundle: all five files named in the Reference Guide table exist in references/ (acceptance-criteria.md, ears-syntax.md, interview-questions.md, pre-discovery-subagents.md, specification-template.md) and are one level deep — the only cross-reference is pre-discovery-subagents.md pointing to a sibling file, still one hop from SKILL.md. The table gives topic, path, and explicit "Load When" conditions, and inline examples are minimal with pointers to full syntax ("load `references/ears-syntax.md` for full syntax"). This matches anchor 5 exactly. | 5 / 5 |
Total | 17 / 20 Passed |