Content
82%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 well-constructed instruction skill: an explicit, numbered workflow with concrete CLI commands, JSON fields to parse, confirmation gates, and clear guardrails. The main gaps are the absence of an explicit post-edit validation step and some redundancy between the step-5 tasks rules and the Guardrails restatement.
Suggestions
Add a post-edit validation step to the workflow (e.g., run `openspec validate` on the change after revisions are written) so the sequence ends with an explicit verification checkpoint.
Consolidate the tasks.md delta-edit rules into one place — either step 5 or the Guardrails section — and have the other reference it, removing the current duplication.
Consider moving the detailed tasks.md requirement-coverage and file-less-task rules into a one-level-deep reference file (e.g., references/tasks-rules.md) to keep the main workflow lean.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and directive throughout — commands, JSON field names, and rules with no padding or explanation of concepts Claude already knows — e.g., "The files to edit are `artifactPaths.<id>.existingOutputPaths`". It is not 5 because the tasks.md delta-edit rules appear twice (step 5 and re-summarized in Guardrails) and the store-selection paragraph could be tightened; it is well above 3 since nearly every sentence is operative. | 4 / 5 |
Actionability | Fully executable guidance: concrete commands (`openspec list --json`, `openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`), the exact JSON fields to parse, and a copy-ready example of the tag syntax ("`- [ ] 3.1 [e2e] Run the full test suite and confirm it passes.`"). Common cases (prompt for change selection, coherence-only request, rejected revision) are all explicitly covered. | 5 / 5 |
Workflow Clarity | A clearly sequenced 6-step workflow with a strong confirmation gate ("Show each proposed revision and why. Write only after the user confirms") and an explicit feedback loop ("If the user rejects a revision, do not write it"), plus an early state check via `openspec status`. It falls short of 5 because there is no explicit post-edit validation step (e.g., running `openspec validate` on the revised artifacts); it stays above 3 because user confirmation before each write provides the checkpoint for this non-destructive, artifacts-only operation. | 4 / 5 |
Progressive Disclosure | The body has clear, well-organized sections (Store selection, Steps, Output, Guardrails) with no references to nonexistent files, and everything is needed at execution time — there is no orphaned or buried reference. It is not 5 because the ~35-line tasks.md delta-rules subsection in step 5 is dense inline content that could plausibly live in a one-level-deep reference file, and the skill exceeds the simple <50-line case the rubric exempts. | 4 / 5 |
Total | 17 / 20 Passed |