Content
67%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, genuinely actionable CLI-driven workflow with concrete commands, explicit state handling, and clear pause checkpoints. Its weaknesses are redundancy — Guardrails and the Fluid Workflow section restate earlier guidance — and missing explicit verification steps (re-running status after marking tasks, a fix-and-retry loop on errors).
Suggestions
Merge the Guardrails bullets that duplicate step 6's Pause-if conditions, and fold the Fluid Workflow Integration section into a single line to remove the third repetition of the artifact-update guidance.
Add an explicit verification step after the implement loop, e.g., re-run `openspec status --change "<name>" --json` to confirm recorded progress before reporting completion.
Add a lightweight error-recovery loop (e.g., on command failure, inspect the error, retry once, then pause and present options) to strengthen the feedback structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient procedural instruction with no concept explanations Claude already knows, but it could be tightened: the Guardrails section re-states the step-6 Pause-if conditions ("If task is ambiguous, pause and ask", "Keep code changes minimal", "suggest artifact updates"), and the Fluid Workflow Integration section repeats the artifact-update guidance a third time. Anchor 3 (some unnecessary duplication) fits better than anchor 4 (only minor instances). | 3 / 5 |
Actionability | Guidance is mostly executable: copy-paste-ready commands (`openspec status --change "<name>" --json`, `openspec instructions apply --change "<name>" --json`, `openspec list --json`), explicit state handling (blocked / all_done / proceed), a concrete tasks-file edit (`- [ ]` → `- [x]`), and full output templates. It stops short of anchor 5 only because "Make the code changes required" is necessarily open-ended and no command verifies progress after marking a task. | 4 / 5 |
Workflow Clarity | A clear 7-step sequence with a per-task implement loop, explicit pause checkpoints (unclear task, design issue, error/blocker, user interrupt), and end-of-session status reporting. Minor validation gaps keep it at anchor 4 rather than 5: no explicit re-run of `openspec status` to verify recorded progress, and error recovery says "report and wait" without a fix-and-retry loop. | 4 / 5 |
Progressive Disclosure | Single-file skill with no bundle files; sections are well-organized (Input, Steps, three output templates, Guardrails) and dynamic detail is properly delegated to the CLI's apply-instructions output rather than inlined. Anchor 4 rather than 5 because the ~145-line body (including three full output templates) sits well past the under-50-line simple-skill case, and the templates could arguably live in a reference file. | 4 / 5 |
Total | 15 / 20 Passed |