Content
75%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 highly actionable, well-sequenced workflow with concrete commands, JSON contracts, format references, and strong safety guardrails around destructive operations. Its main costs are redundancy between the step sections and the Guardrails section, and the lack of a fix-and-revalidate loop after the final validation step.
Suggestions
Deduplicate the Guardrails section: drop the four bullets that restate step 3/4 rules verbatim (artifactPaths-only, caller-supplied subset, fetch-once/reuse-snapshot, stop-on-invalid-instructions) or compress each to a one-line pointer, and state 'Never write an empty ## Requirements section' only once.
Break the store-selection paragraph into a short bullet list (discover ids, append --store to the listed commands, keep it sticky) so the dense prose block is scannable.
In step 5, add a fix-and-revalidate loop: on validation failure, fix the merged main spec and re-run `openspec validate --specs` before reporting, reserving report-and-stop for failures that persist.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes OpenSpec knowledge and avoids concept explanations, but is repetitive: the Guardrails section restates step 3/4 rules nearly verbatim (artifactPaths-only, caller-supplied subset, fetch-once, stop-on-invalid), "Never write an empty `## Requirements` section" appears twice, and the store-selection paragraph is a dense single-block wall. This fits 'mostly efficient but could be tightened' rather than the noticeably padded anchor 2, since the redundancy is restatement of real rules, not filler. | 3 / 5 |
Actionability | Fully executable instruction-only guidance: copy-paste-ready commands ("openspec status --change \"<name>\" --json", "openspec validate --specs"), concrete JSON contracts to read (planningHome.root, artifactPaths.specs.existingOutputPaths, rules), exact file paths, complete delta/main spec format references, and a ready output summary template. | 5 / 5 |
Workflow Clarity | A clear 6-step sequence with a pre-write checkpoint (instructions snapshot, "stop before every main-spec write" on non-zero/invalid JSON) and a post-write `openspec validate --specs` checkpoint with explicit failure handling, plus extensive safety conditions on the destructive spec-deletion path. It falls short of anchor 5 only because a validation failure instructs report-and-stop with no fix-and-revalidate loop. | 4 / 5 |
Progressive Disclosure | A single-file skill (no bundle directories exist) that is well-sectioned with clear headers and no nested-reference or navigation problems, and the inlined format references are needed on every run; however, the ~280-line body keeps stable reference material (format examples, output template) inline where a split could shrink the always-loaded payload, matching 'good structure; minor organization gaps' rather than the well-split anchor 5. | 4 / 5 |
Total | 16 / 20 Passed |