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.
An instruction-only skill body that is exceptionally actionable and workflow-safe: exact CLI commands, JSON field contracts, validation checkpoints, and guardrails against side effects (never auto-creating the openspec/ root). Its only costs are mild redundancy (repeated constraint guidance, a dense store-flag paragraph) and a fully inlined structure that a slightly larger skill might split into a reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every paragraph is operational (command flags, JSON fields, branch handling) and assumes Claude's competence rather than explaining concepts. Minor trimming opportunities exist: the 'context and rules are constraints, not content' guidance appears twice (in step 3 and again in Guardrails), and the store-selection paragraph is convoluted ('Every unscoped example of those commands below is shorthand...'), which keeps it at 'minor instances of over-explanation' rather than the lean 5 anchor. | 4 / 5 |
Actionability | Fully executable guidance throughout: exact commands with flags (`openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`), the exact JSON fields to read (`schemaName`, `artifacts`, `isPlanningComplete`, `resolvedOutputPath`), and concrete handling for edge cases like glob output paths and `skipped` artifacts. It is not the 4 anchor because no pseudocode or missing key details were found. | 5 / 5 |
Workflow Clarity | A clear numbered sequence (select change -> check status -> act by status -> show progress) with explicit validation checkpoints: parse status JSON before acting, verify the artifact file exists at `resolvedOutputPath` after writing, re-read dependencies from disk rather than conversation memory, and STOP rules bounding each invocation. Error-recovery branches (root: null handling, store-declaration errors, the 'no artifacts ready' fallback) match the top anchor's feedback-loop standard. | 5 / 5 |
Progressive Disclosure | The body is self-contained with no bundle files (no references/, scripts/, or assets/ exist) and is organized into well-labeled sections (Store selection, Project check, Input, Steps, Output, Guidelines, Guardrails) with no buried or nested references. At ~116 lines it exceeds the under-50-lines simple-skill case, and some material (store-selection mechanics, the multi-branch project-check matrix) could plausibly live in a reference file, which holds it at 'good structure; minor organization gaps' rather than the ideal split of 5. | 4 / 5 |
Total | 18 / 20 Passed |