Content
75%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 body is a well-structured, highly actionable stance definition: concrete commands, exact artifact paths, a capture-mapping table, and worked example dialogues make the desired behavior unambiguous. Its main weakness is token efficiency — the Guardrails section and the meta-diagram duplicate earlier content, and the long example transcripts inflate length without adding proportional guidance.
Suggestions
Trim the Guardrails section to only non-duplicated rules — "Don't implement" and "Don't auto-capture" restate the opening IMPORTANT note and "The user decides" guidance verbatim in spirit.
Cut or shrink the decorative meta ASCII diagram in the Visualize section; the four worked example dialogues already demonstrate diagram usage concretely.
Consider moving the four example dialogues to a references/ file (e.g., EXAMPLES.md) and keeping a one-line pointer plus the strongest example inline, reducing SKILL.md's token footprint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient instruction content, but the Guardrails section restates rules already covered ("Don't implement" repeats the opening "you must NEVER write code"; "Don't auto-capture" repeats "The user decides... Don't pressure. Don't auto-capture"), and the meta ASCII diagram about using diagrams is decorative rather than instructive. It is not 2 because it never explains concepts Claude already knows (no PDF-style filler); it is not 4 because the redundant restating and the decorative diagram are unnecessary tokens that could be trimmed. | 3 / 5 |
Actionability | For an instruction-only skill the guidance is fully actionable: a copy-paste command ("openspec list --json"), exact artifact paths ("openspec/changes/<name>/proposal.md" etc.), a concrete insight-to-artifact capture table, quoted example offers, and four fully worked example dialogues covering the common entry points. It is not 4 because the examples comprehensively cover the common cases with specific commands, paths, and responses. | 5 / 5 |
Workflow Clarity | The skill deliberately declares "There are no fixed steps" (it is a stance), yet still defines a clear entry procedure (run "openspec list --json"), explicit branching (no change exists vs. change exists, with a numbered 4-step sequence for reading artifacts), and defined endings. It is not 5 because there are no validation/checkpoint steps (though the mode forbids risky writes, so the destructive-operation cap does not apply); it is not 3 because the branching flow and entry check are explicit rather than implicit. | 4 / 5 |
Progressive Disclosure | It is a single self-contained file with no bundle, organized into clearly headed, well-separated sections (Stance, What You Might Do, OpenSpec Awareness, Entry Points, Ending, Guardrails) that are easy to navigate. It is not 5 because the ~100 lines of example dialogues in "Handling Different Entry Points" could arguably live in a separate examples file to keep SKILL.md leaner (and the file exceeds the under-50-line simple-skill case); it is not 3 because the structure is good and nothing that clearly belongs in a separate file is inlined — the dialogues are core teaching material for a conversational stance. | 4 / 5 |
Total | 16 / 20 Passed |