Content
88%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 strong, highly actionable workflow body with copy-paste CLI commands, explicit validation checkpoints, and guardrails for failure paths. The only real gaps are minor: slight redundancy in the constraint warnings and a 90-line inline body with no reference split that keeps it just below top marks on conciseness and progressive disclosure.
Suggestions
Deduplicate the 'context/rules are constraints, not content' warning — state it once (in Artifact Creation Guidelines) instead of twice in step 4a and the guidelines section.
Consider moving the artifact-creation guidelines and guardrails into a reference file (e.g., references/artifacts.md) to keep SKILL.md as a leaner overview, which would also help progressive disclosure.
Trim emphasized filler such as 'IMPORTANT: Do NOT proceed without understanding what the user wants to build' — the conditional 'if no clear input provided' step already implies this.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is an efficient, command-driven workflow with no concept explanations Claude wouldn't know, but has minor trimmable redundancy: the 'context and rules are constraints, not file content' warning appears both in step 4a and again under Artifact Creation Guidelines, and the 'IMPORTANT: Do NOT proceed without understanding' emphasis pads step 1. This matches 'efficient; minor instances of over-explanation that could be trimmed' rather than the lean 5 anchor. | 4 / 5 |
Actionability | Fully executable guidance throughout: copy-paste commands ('openspec new change "<name>"', 'openspec status --change "<name>" --json', 'openspec instructions <artifact-id> --change "<name>" --json'), named tools to use (AskUserQuestion, TodoWrite), and the exact JSON fields to parse (applyRequires, artifacts, template, outputPath, dependencies). Matches 'fully executable; copy-paste ready code or commands; specific examples cover the common cases.' | 5 / 5 |
Workflow Clarity | A clearly sequenced 5-step process with explicit validation checkpoints (re-run 'openspec status' after each artifact, check every applyRequires artifact has status done, 'verify each artifact file exists after writing before proceeding to next'), a create-and-recheck feedback loop, and failure-path guardrails (existing change name → suggest continuing; critically unclear context → ask the user). Validation steps are present, so the batch-operation cap does not apply; matches the top anchor. | 5 / 5 |
Progressive Disclosure | Well-organized sections (Input, Steps, Output, Artifact Creation Guidelines, Guardrails) with no burying or nesting, but the ~90-line body is entirely inline and no bundle files exist; the simple-skill exception (under 50 lines) does not apply. This matches 'good structure; most content is appropriately placed; minor organization gaps' rather than the 5 anchor, which assumes a concise overview or well-signaled references. | 4 / 5 |
Total | 18 / 20 Passed |