Content
75%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 strongly actionable, well-sequenced workflow skill: commands are complete and executable, validation checkpoints are present, and structure is easy to navigate. The main weakness is repetition between the Steps and the Artifact Creation Guidelines/Guardrails sections, and the absence of error-recovery guidance.
Suggestions
Consolidate the duplicated context/rules and dependency-reading guidance into one section to trim tokens.
Add a brief error-recovery step for what to do when an openspec command fails or returns unexpected JSON.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient (command + purpose, no concept explanations Claude already knows), but the context/rules "do NOT include in output" guidance and the dependency-reading rule are each stated twice (step 4a and again in Artifact Creation Guidelines/Guardrails), which could be tightened into one place. | 3 / 5 |
Actionability | All commands ("openspec new change", "openspec status --change <name> --json", "openspec instructions <artifact-id> --change <name> --json") are copy-paste ready with flags, the returned JSON fields are enumerated, and artifact content is explicitly delegated to the CLI's template — fully executable guidance. | 5 / 5 |
Workflow Clarity | A clear five-step dependency-ordered sequence with validation checkpoints (re-run status after each artifact, check applyRequires completion, "Verify each artifact file exists after writing") and an escalation path for unclear input, but there is no error-recovery loop for command failures, keeping it below the feedback-loop anchor 5. | 4 / 5 |
Progressive Disclosure | A well-organized single-file skill with clear sections (Input, Steps, Output, Guidelines, Guardrails) and no external references needed — no bundle files exist to offload to — but the ~97-line body duplicates guidance across the Steps and Artifact Creation Guidelines sections, a minor organization gap versus the cleanly split anchor 5. | 4 / 5 |
Total | 16 / 20 Passed |