Content
68%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-structured, actionable workflow document with concrete commands, state handling, and clear output templates. Its main weakness is the batch task loop lacking a verification checkpoint before marking tasks complete, plus minor redundancy between the Guardrails section and Step 6's pause conditions.
Suggestions
Add a verification step in the task loop (e.g., run tests or `openspec validate` before marking a task '- [x]') so the batch implementation workflow has an explicit validation checkpoint.
Merge the 'Guardrails' section with the Step 6 'Pause if' conditions to remove the duplicated guidance and reduce token cost.
Include a short sample of the `openspec instructions apply --json` output (contextFiles, progress, state fields) so the parsing step is fully executable without guessing the shape.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and procedural with no explanation of concepts Claude already knows, and output templates are token-efficient. Minor redundancy exists: the 'Guardrails' section largely restates the pause conditions already detailed in Step 6, which keeps it below the 'every token earns its place' anchor 5. | 4 / 5 |
Actionability | Provides copy-paste-ready CLI commands ('openspec status --change "<name>" --json', 'openspec instructions apply --change "<name>" --json'), a concrete edit instruction ('- [ ]' → '- [x]'), and concrete output templates. Minor gaps (no sample JSON output, no example of a task line) keep it below fully-executable anchor 5. | 4 / 5 |
Workflow Clarity | The 7-step sequence is clearly ordered with explicit state handling (blocked, all_done) and pause conditions, which exceeds anchor 3's sequence quality. However, the task loop is a batch operation over multiple tasks with no validation/verification step (e.g., run tests or check the change before marking '- [x]'), which caps the score at 3 per the rubric's batch-operation guideline. | 3 / 5 |
Progressive Disclosure | The skill is self-contained with no bundle files; content is well-sectioned (Steps, Outputs, Guardrails, Fluid Workflow) and all of it appropriately belongs in SKILL.md rather than separate files. At ~150 lines it exceeds the under-50-line simple-skill exception, so it sits at anchor 4 rather than 5. | 4 / 5 |
Total | 15 / 20 Passed |