Content
57%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 conveys a coherent, well-organized behavioral stance with genuinely concrete anchors (commands, artifact paths, capture table, example dialogues). Its weaknesses are redundancy across the stance, entry-points, and guardrails sections, an oversized inline example gallery with no bundle files, and an intentionally loose workflow that leaves checkpoints implicit.
Suggestions
Consolidate the duplicated rules: state the never-implement, don't-auto-capture, and do-visualize guidance once (e.g., keep only the Guardrails section) and trim the rest.
Move the four 'Handling Different Entry Points' ASCII dialogue examples into a references/ file (e.g., examples.md) and keep one short inline example plus a clearly signaled pointer, cutting SKILL.md substantially.
Tighten the workflow around the opening context check: make the change-exists / no-change branch and the optional capture step an explicit short sequence so the flow is unambiguous even though the mode is a stance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body mostly avoids explaining things Claude already knows, but it repeats key rules across sections - "NEVER write code" appears in both the IMPORTANT block and Guardrails, and "don't auto-capture" and "do visualize" are each stated twice - and the four ASCII dialogue examples run roughly 100 lines. It fits 'mostly efficient but could be tightened' rather than the 4 anchor's 'minor instances'. | 3 / 5 |
Actionability | Provides concrete, executable elements - the `openspec list --json` command, exact artifact paths like `openspec/changes/<name>/proposal.md`, a capture-destination table, and example offer phrasings - but a substantial portion is stance description rather than executable guidance, so it stops short of fully copy-paste-ready. | 4 / 5 |
Workflow Clarity | There is an explicit opening check (`openspec list --json`) with a two-way branch (change exists / doesn't) and a numbered 4-step sequence for the change-exists path, but the skill is deliberately 'a stance, not a workflow', so sequencing beyond the entry check is implicit and no validation checkpoints exist. This matches 'steps listed but validation gaps; checkpoints missing or implicit' rather than the 4 anchor's 'clear sequence with most checkpoints'. | 3 / 5 |
Progressive Disclosure | Section headers are clear and well-organized, but there are no bundle files at all: the ~100-line entry-point example gallery and the insight-capture table are inlined in a single 290-line SKILL.md where they could live in a reference file. This matches 'some structure but could be better organized; content that should be separate is inline'. | 3 / 5 |
Total | 13 / 20 Passed |