Content
67%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 instruction-only skill that gives a thinking-partner stance concrete teeth: exact CLI commands, a capture table, explicit feedback loops via re-running status, and vivid worked examples. The main costs are token efficiency — repetitive store-flag parentheticals and two enormous run-on procedural paragraphs — and a missed opportunity to externalize the long entry-point examples.
Suggestions
State the sticky --store rule once and reference it (e.g. 'append the confirmed store flag to every command below'), removing the six repeated parentheticals from the capture steps.
Rewrite steps 2 and 4 of 'When no change exists' as short numbered bullets or a decision list for the conditional-prerequisite/skip logic; the current nested prose is the least actionable part of the skill.
Move the four full entry-point transcripts (roughly 120 lines) to a references/entry-points.md file and keep one exemplar inline, slimming SKILL.md to its stance, commands, and capture rules.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core stance guidance (The Stance, Guardrails) is efficient and assumes Claude's competence, but there is real tightening to do: the parenthetical '(append the confirmed `--store "<id>"`...)' repeats roughly six times across the capture steps, steps 2 and 4 of 'When no change exists' are run-on paragraphs of nested conditionals, and the manual-scaffolding prohibition appears both inline and again in Guardrails. This fits anchor 3 (mostly efficient but could be tightened) rather than 2, since the padding is repetition and over-long sentences rather than explanations of concepts Claude already knows. | 3 / 5 |
Actionability | Concrete, executable commands are given throughout (openspec list --json, openspec new change "<name>", openspec status --change "<name>" --json, openspec instructions "<artifact-id>"...), plus a specific insight-to-artifact capture table and worked conversational examples for four entry points. It stays below anchor 5 because the conditional-prerequisite logic in steps 2 and 4 is written as dense prose that leaves execution ambiguous in edge cases, though it is well above anchor 3 since the guidance is real and executable, not pseudocode. | 4 / 5 |
Workflow Clarity | The capture workflows are numbered with explicit checkpoints and feedback loops: 'After creating each artifact, re-run openspec status --change "<name>" --json... and continue until every requested artifact is done, skipped', and 'Verify that the selected concrete output exists'. This matches anchor 4 (clear sequence with most checkpoints present) rather than 5 because there is no explicit validation of created artifacts (the validate command is listed among store-capable commands but never invoked in the workflow), and the deeply nested skip/prerequisite rules make the sequence harder to follow than a checklist would. | 4 / 5 |
Progressive Disclosure | As a single-file skill with no bundle files, it is well organized: clearly signaled sections (The Stance, What You Might Do, OpenSpec Awareness, Handling Different Entry Points, Guardrails) each with a distinct job and no nested references. It fits anchor 4 rather than 5 because roughly a third of the body is example transcripts and the dense artifact-capture procedure, which could be split into a references/ file (e.g. entry-point examples) to keep the main body lean; it is above anchor 3 since structure and navigation are clear, not merely present. | 4 / 5 |
Total | 15 / 20 Passed |