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 is a well-sequenced, highly actionable tutorial script with clear phase structure, explicit pauses, and thoughtful edge-case handling (preflight failure, oversized tasks, mid-way exits). Its weaknesses are redundancy (duplicated command tables, restated guardrails), a missing verify-before-archive checkpoint, and everything inlined in a single long file rather than split into references.
Suggestions
Add a verification step between implementation and archive (e.g. run /opsx:verify or the project's tests, fix and re-run if failing) so the workflow has a feedback loop before the destructive archive move.
Deduplicate the command reference: it appears nearly verbatim in both Phase 11's recap and the graceful-exit section — keep one canonical table and point to it from the other.
Move the artifact format templates (proposal/spec/design/tasks skeletons) and the command reference into a references/ file (e.g. references/artifact-templates.md), keeping SKILL.md as a lean walkthrough script.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly purposeful since a scripted tutorial legitimately needs its display templates, but it could be tightened: the command reference table appears twice nearly verbatim (Phase 11 recap and the graceful-exit command-reference section), and the Guardrails section restates rules already embedded in the phases. This matches the anchor for mostly efficient content with some unnecessary explanation or tightening opportunities. | 3 / 5 |
Actionability | Guidance is highly concrete — exact commands ("openspec new change \"<derived-name>\"", "openspec archive \"<name>\"", preflight with CLI_NOT_INSTALLED fallback), full display templates, and per-phase EXPLAIN/DO/SHOW/PAUSE instructions. Minor gaps remain: "openspec instructions proposal --change \"<name>\" --json" is given without explaining how to consume its JSON output, and file writes are described but not scripted, so it does not reach fully copy-paste-ready anchor 5. | 4 / 5 |
Workflow Clarity | Excellent sequencing: Preflight validates the CLI and stops if missing, phases 1-11 follow a consistent EXPLAIN/DO/SHOW/PAUSE pattern with marked PAUSE checkpoints, a scope guardrail, and graceful exit handling. The gap is that Phase 9 implementation proceeds directly to Phase 10 archive with no verification step (/opsx:verify is only mentioned in a table, never invoked in the flow), matching the anchor for a clear sequence with minor validation gaps. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent) and no external files are referenced; all ~555 lines live inline in SKILL.md. Phase-based section structure makes it navigable, but content that belongs in separate reference files — the artifact format templates (proposal/spec/design/tasks) and the duplicated command reference tables — is inlined, matching the anchor for some structure with content that should be separate kept inline. | 3 / 5 |
Total | 14 / 20 Passed |