Content
77%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 content is highly actionable and its workflows are clearly sequenced with explicit validation checkpoints and error-recovery paths. However, it is a monolithic ~345-line single file with significant repetition (especially the --store flag instructions and confirmation guardrails) that would benefit from tighter prose and splitting detailed procedure into reference files.
Suggestions
State the sticky --store <id> rule once in the Store selection section and refer back to it ('with --store when selected') in later steps, removing the ~8 verbatim repetitions.
Extract the detailed 4-step capture workflow and the artifact-creation rules (path resolution, dependency handling, conditional skips) into a reference file such as references/capture-workflow.md, keeping SKILL.md as an overview with a clearly signaled link.
Consolidate the write-confirmation guardrails into a single section - they are currently stated in the opening IMPORTANT paragraph, again under 'Don't auto-capture', and again in the capture transition.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly task-relevant but noticeably repetitive: the instruction to append the confirmed --store flag is stated in the Store selection section and then repeated in nearly every numbered step (~8 times), and the write-confirmation guardrails are stated three times (intro paragraph, 'Don't auto-capture', and the capture transition). Not 2 because there is no padding of concepts Claude already knows. | 3 / 5 |
Actionability | Guidance is copy-paste ready and covers the common cases: exact commands with flags (`openspec list --json`, `openspec show "<spec-id>" --type spec --json --no-scenarios`, `openspec new change "<name>"`), named JSON fields to read (`root`, `changeRoot`, `artifactPaths`, `resolvedOutputPath`), example dialogues for four entry points, and a table mapping insight types to capture destinations. | 5 / 5 |
Workflow Clarity | The capture workflow is explicitly sequenced with feedback loops and validation checkpoints: 'After creating each artifact, re-run openspec status', verifying chosen output paths stay inside changeRoot after resolving symlinks, verifying the concrete output exists, and explicit error-recovery handling for blocked prerequisites and conditional skips. The stance sections intentionally and clearly state there is no fixed sequence. | 5 / 5 |
Progressive Disclosure | No bundle files exist and all ~345 lines live inline in SKILL.md. Section headers and horizontal rules make it navigable, but the dense capture-workflow steps and the store-scoping rules are exactly the kind of detailed material that belongs in one-level-deep reference files, leaving the main file an overview. This matches the 'content that should be separate is inline' anchor rather than the well-split anchor 4. | 3 / 5 |
Total | 16 / 20 Passed |