Content
81%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 instruction-only skill body: fully executable CLI commands, a dependency-aware creation loop with real validation checkpoints, and explicit handling of ambiguous input. The only notable issue is redundancy — the Artifact Creation Guidelines section repeats constraints and steps already given in step 4.
Suggestions
Merge the "Artifact Creation Guidelines" section into step 4a and state the context/rules constraint once, cutting roughly 10 lines of duplication.
Add a brief error-recovery note for CLI failures (e.g., what to do if `openspec instructions` errors or the scaffold step fails) to round out the feedback loop.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean commands and steps, but the "Artifact Creation Guidelines" section substantially restates step 4a: the context/rules-as-constraints point ("context: Project background (constraints for you - do NOT include in output)") is repeated with three sub-bullets and a second IMPORTANT marker. Not 2 because most of the file is efficient and unpadded; not 4 because the duplication is a whole redundant section, beyond minor trimmable instances. | 3 / 5 |
Actionability | All commands are copy-paste ready (`openspec new change "<name>"`, `openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`), the JSON response fields to parse are enumerated, and edge cases (missing input, unclear context, existing change) are explicitly handled. Deferring artifact content to the CLI's runtime `template` is a justified design, not a gap, so anchor 5 applies. | 5 / 5 |
Workflow Clarity | Clear dependency-ordered sequence with explicit validation checkpoints ("re-run `openspec status`... Check if every artifact ID in `applyRequires` has `status: 'done'`", "Verify each artifact file exists after writing before proceeding to next"), an explicit stop condition, a user-input feedback loop via AskUserQuestion, and TodoWrite progress tracking. Meets anchor 5; the batch-operation validation cap does not apply since validation is present. | 5 / 5 |
Progressive Disclosure | Sections are well organized (Input / Steps / Output / Artifact Creation Guidelines / Guardrails) and no external reference files are needed because all artifact-specific detail is sourced dynamically from the `openspec` CLI. However, the body is ~90 lines in a single file and the Guidelines section duplicates step 4 content — a minor organization gap that keeps it below anchor 5 and comfortably above anchor 3. | 4 / 5 |
Total | 17 / 20 Passed |