Content
63%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 delivers a highly actionable, clearly sequenced 11-phase tutorial with explicit pause checkpoints and robust fallback handling. Its main weaknesses are duplicated command-reference content and the absence of any verification step before archiving, plus no use of separate reference files for the template/command material.
Suggestions
Deduplicate the command reference tables (Phase 11 and Graceful Exit) into a single section, or move them to a references/commands.md file.
Insert a verification step between implementation and archive, e.g. running "openspec verify" or /opsx:verify, to close the feedback loop.
Tighten the display templates by trimming placeholder prose, and consider moving the artifact templates (proposal/spec/design/tasks) into a references/ file for progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly purposeful (scripted display templates are the product of this teaching skill), but the command reference tables are duplicated verbatim in Phase 11 and the Graceful Exit section, and several templates carry placeholder padding that could be tightened. | 3 / 5 |
Actionability | Concrete executable commands are given throughout ("openspec new change \"<derived-name>\"", "openspec archive \"<name>\"", preflight check with fallback output) alongside exact display templates and file paths. Minor gap: artifact saves are described ("Then write the content to openspec/changes/<name>/proposal.md") rather than given as fully copy-paste-ready steps. | 4 / 5 |
Workflow Clarity | Eleven clearly numbered phases with explicit PAUSE checkpoints, a preflight CLI validation, fallbacks (no suggestions found, scope guardrail, graceful exit) form a strong sequence. Minor validation gap: there is no verification step between implementation (Phase 9) and archive (Phase 10), e.g. invoking the documented /opsx:verify, which keeps it below the anchor-5 feedback-loop standard. | 4 / 5 |
Progressive Disclosure | The skill is a single well-sectioned SKILL.md with no bundle files. Content such as the command reference tables (duplicated twice) and the artifact templates could live in a references/ file to keep SKILL.md a lean overview, so structure is present but organization could be improved. | 3 / 5 |
Total | 14 / 20 Passed |