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.
The body delivers a clear, well-structured stance with genuinely concrete OpenSpec commands and a capture workflow that includes validation feedback loops. Its weaknesses are verbosity from repeated store-flag guidance and redundant sections, and capture-workflow steps written as dense conditional paragraphs rather than scannable checklists.
Suggestions
State the '--store' stickiness rule once (in the Store selection section) and refer back to it from the workflow steps instead of repeating the parenthetical in steps 2, 3, and 4.
Merge 'What You Don't Have To Do' and 'Guardrails' or trim overlaps with 'This is a stance, not a workflow' to cut redundant tokens.
Break the run-on conditional paragraphs in the capture workflow into a short checklist with an explicit 'after each artifact: re-run status' checkpoint for both the new-change and existing-change branches.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — stance bullets, concrete commands, and example dialogues all earn their place — but it has noticeable tightening opportunities: the '--store' stickiness rule is restated nearly verbatim in the Store-selection paragraph and again inside steps 2, 3, and 4 of the capture workflow, and the 'What You Don't Have To Do' and 'Guardrails' sections repeat points already made by 'This is a stance, not a workflow' and 'Don't auto-capture'. This fits anchor 3 (mostly efficient but could be tightened) rather than anchor 2, since the padding is redundancy in otherwise valuable guidance, not explanation of concepts Claude already knows. | 3 / 5 |
Actionability | Concrete, executable commands appear throughout: `openspec list --json`, `openspec new change "<name>"`, `openspec status --change "<name>" --json`, `openspec instructions "<artifact-id>" --change "<name>" --json`, plus a specific decision table mapping insight types to capture locations. This matches anchor 4 (mostly executable guidance with minor gaps); it does not reach anchor 5 because several directives remain necessarily abstract ('Follow the returned template and instruction fields', 'Use root.path returned above') without worked examples of the JSON fields in play, and it is above anchor 3 because the guidance that can be concrete is given as exact commands rather than pseudocode. | 4 / 5 |
Workflow Clarity | The capture workflow is a clearly numbered 1-4 sequence with an explicit validation feedback loop in step 4 ('After creating each artifact, re-run `openspec status --change "<name>" --json` ... and continue until every requested artifact is done, skipped, or was deliberately skipped'), and error-recovery paths (blocked prerequisites, conditional skips) are enumerated. This fits anchor 4 (clear sequence with most checkpoints present). It falls short of anchor 5 because steps 2-4 are dense run-on paragraphs with nested conditionals that are hard to follow as a checklist, and the 'when a change exists' branch has checkpoints ('re-run status') only implied rather than stated. | 4 / 5 |
Progressive Disclosure | There are no bundle files, so everything lives in SKILL.md (~290 lines), but the single file is well organized into clear, well-signaled sections (The Stance, What You Might Do, OpenSpec Awareness, Handling Different Entry Points, Ending Discovery, Guardrails) that are easy to navigate. This matches anchor 4 (good structure; most content appropriately placed). It does not reach anchor 5 because the ~100 lines of example dialogues in 'Handling Different Entry Points' are content that could plausibly live in a references file, and it is above anchor 3 because nothing that clearly belongs in a separate file (like an API reference) is inlined and no nested or buried references exist. | 4 / 5 |
Total | 15 / 20 Passed |