Content
64%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 is well organized and unusually actionable for a stance-based skill, with concrete commands, artifact paths, and example phrasings throughout. Its weaknesses are length — heavy illustrative transcript sections that could be cut or condensed — and the absence of any progressive disclosure despite being well past overview size.
Suggestions
Move the four 'Handling Different Entry Points' transcripts into a references/entry-points.md and keep one condensed example inline, cutting the body roughly by a third.
Trim the standalone ASCII demo in the 'Visualize' bullet list since the entry-point examples already demonstrate diagramming.
Add a short note on what to do when `openspec list --json` fails or no OpenSpec project exists, since that is the skill's first checkpoint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's intelligence (no concept explanations) but the ~100-line 'Handling Different Entry Points' section of full ASCII-dialogue transcripts and the earlier standalone diagram demo are noticeably trimmable, matching 'mostly efficient but could be tightened' rather than the minor-trim bar of 4. | 3 / 5 |
Actionability | Concrete and executable for an instruction-only skill: the exact command `openspec list --json`, real artifact paths (`openspec/changes/<name>/proposal.md`, `design.md`, `tasks.md`), an insight-to-artifact capture table, and verbatim offer phrasings. Minor gaps remain, such as what to do when no OpenSpec project is initialized. | 4 / 5 |
Workflow Clarity | An explicit opening checkpoint ('At the start, quickly check what exists: openspec list --json') and a numbered four-step capture sequence ending in 'The user decides - Offer and move on' give clear sequencing. It falls short of 5 because the deliberately stance-based flow leaves transition points (when to re-check context, when to move from exploring to offering capture) implicit. | 4 / 5 |
Progressive Disclosure | The file is well-sectioned with clear headers, but it is a ~280-line monolith with no bundle: the four entry-point example transcripts and the OpenSpec capture table are content that clearly belongs in a one-level-deep reference file, matching 'some structure but content that should be separate is inline'. | 3 / 5 |
Total | 14 / 20 Passed |