Content
56%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 genuinely actionable, well-sequenced guidance with explicit validation checkpoints and confirmation gates, and it never wastes tokens on concepts Claude already knows. Its weaknesses are mechanical redundancy — the --store flag rule repeated verbatim on nearly every command and confirmation rules stated three times — and a monolithic structure with no progressive disclosure into reference files.
Suggestions
State the --store flag rule once and stop: the 'Store selection' paragraph already declares the flag sticky and defines unscoped examples as shorthand, so delete the '(append the confirmed --store "<id>" only for a registered standalone store)' parenthetical repeated on roughly eight commands.
Consolidate the write-confirmation rules into one canonical statement: the same guardrail appears in the intro paragraph, 'Keep a conversational record', and 'Don't auto-capture'; keep the most detailed version and cross-reference it elsewhere.
Split the capture-transition steps (and possibly the entry-point dialogue examples) into a reference file under references/ and link to it from SKILL.md, so the body stays a lean overview of the stance with detailed mechanics disclosed on demand.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The --store stickiness rule is stated once ('treat --store <id> as sticky for the rest of the workflow') yet the parenthetical '(append the confirmed --store "<id>" only for a registered standalone store)' is repeated on roughly eight individual commands anyway, and write-confirmation rules appear three times (intro, 'Keep a conversational record', 'Don't auto-capture'). This is noticeably verbose with several padded, redundant sections, though it never explains concepts Claude already knows. | 2 / 5 |
Actionability | Concrete executable commands with exact flags throughout ('openspec list --json', 'openspec show "<spec-id>" --type spec --json --no-scenarios', 'openspec new change "<name>"', 'openspec status --change "<name>" --json') plus dialogue examples. Minor gap: step 2 of the capture transition packs nested conditionals into one run-on sentence, making it hard to follow cleanly. | 4 / 5 |
Workflow Clarity | The capture sequence is numbered with an explicit feedback loop ('re-run openspec status --change "<name>" --json and continue until every requested artifact is done, skipped...'), a root-validation checkpoint ('read root... read the JSON instead of retrying'), and confirmation gates before writes. Not 5 because step 2's tangled conditionals and the 'dependencies are enablers, not gates' exception obscure the sequence. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned with clear headers, but it is a ~343-line monolith with no references to separate files, and content that could live in a reference (capture-transition mechanics, entry-point dialogue examples) is fully inlined. No bundle files exist to offset this. | 3 / 5 |
Total | 13 / 20 Passed |