Content
63%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 delivers a clear, concrete stance definition with executable OpenSpec CLI workflows and good validation loops for artifact capture. Its weaknesses are token efficiency — systematic repetition of the --store flag instruction and oversized ASCII examples — and a monolithic structure where the detailed capture procedure and dialogue examples should be split into reference files.
Suggestions
State the --store flag rule once in the store-selection paragraph and refer back to it ("apply the sticky store flag to every command that takes it") instead of repeating the parenthetical six times (conciseness).
Move the dense conditional change-capture procedure into a references/capture-workflow.md and keep a short summary in SKILL.md, so the main file stays a lean overview (progressive_disclosure).
Trim the four ASCII mock-dialogues to one or two compact examples — the pattern (diagram + open question) is clear after the first (conciseness).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core stance guidance is tight, but there is real padding: the parenthetical "(append the confirmed --store \"<id>\" only for a registered standalone store)" is repeated nearly verbatim six times across the store-selection and capture sections, and the four long ASCII mock-dialogues (~100 lines) illustrate points Claude could grasp from one shorter example. Mostly efficient with clear tightening opportunities — fits the 3 anchor, not 4, because the repetition is systematic rather than minor. | 3 / 5 |
Actionability | Concrete, copy-paste-ready commands appear throughout ("openspec list --json", "openspec new change \"<name>\"", "openspec status --change \"<name>\" --json") with specific JSON fields to consume (changeRoot, artifactPaths.existingOutputPaths, resolvedOutputPath) and verify against. Not 5 because the stance/entry-point sections rely on abstract direction where a concrete decision rule would help (e.g., when to offer capture vs. keep exploring). | 4 / 5 |
Workflow Clarity | The change-capture path is well sequenced with explicit checkpoints and feedback loops: scaffold via CLI, re-run "openspec status --json" after each artifact, process in dependency order, verify the concrete output exists, and loop until every artifact is done/skipped. Not 5 because the exploration flow itself deliberately has no checkpoints (acceptable for a stance skill), and the conditional-skip/dependency-override rules in step 4 are dense enough that a checkpoint summary would help. | 4 / 5 |
Progressive Disclosure | The file is well-sectioned with clear headers, but it is a ~300-line monolith with zero external references: the dense conditional change-capture procedure (lines 110-117) and the long entry-point dialogue examples are exactly the kind of detail that belongs in a one-level-deep reference file, keeping SKILL.md a lean overview. This matches the 3 anchor ("content that should be separate is inline") better than 4, which expects most bulk content appropriately split out. | 3 / 5 |
Total | 14 / 20 Passed |