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.
A well-structured, highly actionable CLI workflow skill with copy-paste-ready commands, explicit validation before writes, and clear stopping points. The main cost is token weight in the long store-selection and project-check prose, which could be compressed or moved to a reference file.
Suggestions
Tighten the store-selection paragraph: instead of enumerating all eleven commands that take --store and re-explaining the shorthand convention, state the rule once ('append --store <id> to any command that reads or writes specs/changes') and list the exceptions only if needed.
Compress the project-check edge cases (the 'Declared in' / 'Invalid store declaration in' branch) into a short bullet or move them to a reference file, keeping only the core instruction to run 'openspec list --json' and read 'root' inline.
Add a brief fallback in step 5 for when no artifact has status 'ready' in the status output, so the sequence is fully closed under errors.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is operational rather than padded with concepts Claude already knows, but the store-selection paragraph enumerates all eleven flag-taking commands and re-explains the shorthand convention, and the project-check section spends multiple paragraphs on error-message edge cases. Mostly efficient but these sections could be tightened. | 3 / 5 |
Actionability | Provides copy-paste-ready commands ('openspec new change "<name>"', 'openspec status --change "<name>" --json'), a verbatim question to ask the user, and explicit JSON fields to read (planningHome, changeRoot, nextSteps). For an instruction-only skill, the guidance is fully executable and covers the common cases. | 5 / 5 |
Workflow Clarity | A clear 1-6 sequence with an explicit STOP checkpoint, a pre-write validation gate ('openspec list --json', read root) with error-recovery branches for non-zero exits, and a guardrails section. Not a 5 because step 5's instruction to find the first artifact with status 'ready' has no fallback if none is ready. | 4 / 5 |
Progressive Disclosure | Well-organized labeled sections (Store selection, Project check, Input, Steps, Output, Guardrails) with no nested references and appropriately inline steps. At ~75 lines, the dense store-selection and project-check prose blocks arguably belong in a reference file, which keeps it below the top anchor. | 4 / 5 |
Total | 16 / 20 Passed |