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.
This is a high-quality instruction skill: all guidance is novel and project-specific, paths and tooling are exact, and the worked example makes the expected output shape unambiguous. The main improvements available are removing the small duplications (Figma rules, invariant-style guidance repeated across sections) and moving the long example to a references file.
Suggestions
State the Figma-mock rules once (in "Before writing") and have the Structure section's Figma bullet reference it in one line instead of restating the "Figma: none provided" convention in both places.
Consolidate the invariant-style guidance: "Write Behavior as a list of invariants" appears in Structure, The Behavior section, and Writing guidance — keep it in The Behavior section and drop the restatements.
Move the worked markdown-tables Behavior example to references/example-behavior.md and link to it, keeping SKILL.md to the policy and structure guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific conventions Claude could not know (spec directory rules, Figma handling, section policy, a worked example) and assumes competence rather than explaining basics. Minor duplication could be trimmed — the Figma rules appear in both "Before writing" and "Structure", and "write Behavior as numbered invariants" is stated in three places — which keeps it below the lean anchor 5. | 4 / 5 |
Actionability | For an instruction-only skill the guidance is fully concrete: exact paths ("specs/<id>/PRODUCT.md") with three id formats and examples, named tools ("ask_user_question", "Linear MCP tools", "gh" CLI), a precise section checklist with include/omit rules, and a complete worked Behavior example that is copy-paste ready as a model. Every instruction is executable without guessing. | 5 / 5 |
Workflow Clarity | The sequence is clear: gather context ("Gather only the context you need... Use ask_user_question for missing context rather than guessing"), ask about Figma mocks before drafting Behavior, write to the structured template, then hand off to write-tech-spec, with an explicit done-check ("If a reader finishes Behavior with questions about what the feature does in some situation, the section is not done"). It lacks a numbered step list with explicit validation gates per step, so it falls short of the anchor 5 feedback-loop pattern; the workflow is not destructive or batch, so no cap applies. | 4 / 5 |
Progressive Disclosure | No bundle files exist, so the single-file structure is judged on its own organization: well-labeled sections (Overview, Before writing, Structure, Behavior, Length heuristic, Writing guidance, Example) make navigation easy. The ~45-line example Behavior section is the one block that could live in a references/ file to keep the overview lean, which is a minor organization gap rather than a structural problem. | 4 / 5 |
Total | 17 / 20 Passed |