Content
81%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.
Highly actionable content with concrete CLI commands, an explicit capture workflow with validation checkpoints, and vivid worked examples. The main cost is token efficiency: repeated store-flag parentheticals and redundant stance restatements could be consolidated without losing clarity.
Suggestions
Consolidate the store-selection guidance: state the sticky --store rule once and refer to it in the numbered steps instead of repeating the '(append the confirmed --store "<id>"...)' parenthetical after every command.
Trim or merge the 'What You Don't Have To Do' section, which largely restates 'This is a stance, not a workflow' from the introduction.
Shorten the four inline entry-point dialogues to one representative example and reference the others, or move the fuller dialogues to a references file to reduce the body's token footprint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient and example-driven, but the '(append the confirmed --store "<id>"...)' parenthetical is repeated roughly six times across the capture steps, and the 'What You Don't Have To Do' section restates 'This is a stance, not a workflow' from the intro. Fits 'mostly efficient but includes some unnecessary explanation or could be tightened'; not 2 because the padding is localized and the examples genuinely instruct. | 3 / 5 |
Actionability | Concrete, copy-paste-ready commands throughout ('openspec list --json', 'openspec new change "<name>"', 'openspec status --change "<name>" --json'), an explicit capture table mapping insight types to artifact paths, and worked example dialogues covering the common entry points. Fully actionable for an instruction-only skill. | 5 / 5 |
Workflow Clarity | The capture workflow is clearly sequenced with explicit validation checkpoints: scaffold via CLI before any artifacts, 'Verify that the selected concrete output exists', re-run 'openspec status' after each artifact, and continue until every requested artifact is done or deliberately skipped. This matches the top anchor with a feedback loop for error recovery. | 5 / 5 |
Progressive Disclosure | The single SKILL.md is well-sectioned (stance, activities, OpenSpec awareness, entry points, ending, guardrails) with a clear overview, but at ~295 lines the four long inline example dialogues create minor organization gaps. Fits 'good structure; most content is appropriately placed; minor organization gaps'; not 5 because there are no well-signaled references and some example material could be split out. | 4 / 5 |
Total | 17 / 20 Passed |