Content
77%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 workflow is exceptionally actionable and clearly sequenced with explicit validation and recovery paths. Its weaknesses are repetition that inflates the token budget and a monolithic single-file structure that inlines what should be one-level-deep reference material.
Suggestions
Consolidate the planning-boundary rule into one authoritative statement and have the Guardrails and Output sections reference it, rather than restating it three times; do the same for the --store flag rule across the store-selection, project-check, and step-4 sections.
Extract the store-selection rules and the project-check decision tree (auto-selected vs. explicit request branches) into a references/ file (e.g., references/store-and-project-check.md), leaving SKILL.md as a lean overview that points to it.
Replace bold-paragraph pseudo-headers with real markdown section headers so the steps, guidelines, and guardrails are scannable and navigable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body avoids teaching concepts Claude already knows, but it repeats key rules multiple times: the planning boundary appears in the intro, Guardrails, and Output sections; the --store flag rule is restated across several paragraphs; "re-read dependencies from disk" appears twice. Meaningful tightening is possible. | 3 / 5 |
Actionability | Every step gives copy-paste-ready commands (e.g., `openspec new change "<name>"`, `openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`) with the exact JSON fields to parse and concrete per-branch handling of failure modes. | 5 / 5 |
Workflow Clarity | Steps 1-7 are clearly sequenced with explicit validation checkpoints (re-run `status` after each artifact, verify the file exists after writing, check `root` before any write) and explicit error-recovery feedback loops for `"root": null`, store declaration errors, and context failures. | 5 / 5 |
Progressive Disclosure | No bundle files exist and everything is inlined in one ~160-line file organized with bold pseudo-headers rather than real sections. Self-contained material such as the store-selection rules and the project-check decision tree reads as reference content that belongs in a separate file. | 3 / 5 |
Total | 16 / 20 Passed |