Content
81%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.
A highly actionable, well-sequenced workflow with strong validation checkpoints and error-recovery guidance throughout. Its main weakness is token efficiency: conditional rules around stores, roots, and the planning boundary are stated repetitively and could be materially tightened or moved into a shared reference file.
Suggestions
State the planning boundary once (either the opening section or Guardrails) and cross-reference it from the other location instead of repeating it in full.
Condense the Store selection and Project check sections into a compact rule table or short bullet list; the --store flag scoping is currently explained three separate times.
Move the store-selection/project-check/root-resolution boilerplate into a shared reference file (e.g. references/store-and-root.md) that the OpenSpec workflow family can point to, slimming SKILL.md to the propose-specific steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | There is no basic-concept padding and the dense edge-case rules (skip_specs handling, symlink checks, the 51,200-byte context limit) earn their tokens, but the body is noticeably verbose: the store-selection paragraph repeats the --store rules multiple times, and the planning boundary is stated in full both in the opening section and again in Guardrails. Several passages could be tightened without losing information, matching anchor 3 ('mostly efficient but could be tightened') rather than anchor 4's minor-trim bar. | 3 / 5 |
Actionability | Every step gives copy-paste-ready commands with exact flags (e.g. `openspec new change "<name>"`, `openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`) and specifies which JSON fields to read and how to act on each (applyRequires, requires edges, root, message/fix). Anchor 5: fully executable guidance covering the common cases. | 5 / 5 |
Workflow Clarity | A clear 7-step sequence with explicit validation checkpoints: a project check before any write, re-running `openspec status --json` after each artifact to recompute the required set, verifying each artifact file exists after writing, and defined error-recovery paths (stop and show the status error's message and fix rather than retrying). This matches anchor 5's explicit validation with feedback loops; nothing is missing for this file-writing workflow. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so everything lives in SKILL.md, but the body is well-sectioned (Planning boundary, Store selection, Project check, Steps, Output, Guidelines, Guardrails) and appropriately defers artifact-specific detail to the CLI's own `instructions` output rather than inlining it — an effective one-level deferral. It is not anchor 5 because the store-selection/project-check boilerplate, likely shared across the OpenSpec workflow family, is fully inlined instead of split into a reference file; it is above anchor 3 because structure and navigation are genuinely good. | 4 / 5 |
Total | 17 / 20 Passed |