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 well-engineered workflow skill: fully executable commands, explicit validation and error-recovery branches, and disciplined guardrails (one artifact per invocation, re-read dependencies from disk). The body is efficient and specific throughout, with only minor organizational and conciseness refinements available.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with operational specifics and avoids explaining concepts Claude already knows, but has minor trim opportunities: "stop and tell the user" is repeated across sections, the changeRoot symlink check is explained twice (in the partly-written-artifact section and again in the ready-artifact branch), and several long parentheticals could be tightened. Anchor 4 (efficient with minor over-explanation) fits better than 3, since nearly every sentence carries non-obvious CLI-specific information. | 4 / 5 |
Actionability | Commands are copy-paste ready (`openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`, `openspec list --json`, `openspec store list --json`), the JSON fields to parse are enumerated by name, and each status branch ends in a concrete action. This matches anchor 5 for an instruction-only skill; per the scoring notes, absence of code is not penalized when guidance is this actionable. | 5 / 5 |
Workflow Clarity | The four-step sequence is explicit with validation checkpoints throughout: verify expected files against `artifactPaths`, verify output paths remain inside `changeRoot` after resolving symlinks, verify the artifact file exists after writing, and re-run `openspec status` to show progress. Error-recovery feedback loops are present for the failure modes (root:null branching, unresolvable store declarations, interrupted glob artifacts, ambiguous change selection). This matches anchor 5; anchor 4 would require missing checkpoints, and none are missing for this non-destructive, single-artifact workflow. | 5 / 5 |
Progressive Disclosure | As a single-file skill with no bundle files, all runtime-needed content is appropriately inline and organized under clear sections (Store selection, Project check, Input, Steps, Output, Artifact Creation Guidelines, Guardrails). It scores 4 rather than 5 because at ~125 lines it exceeds the under-50-line simple-skill exception, and the `---`-separated decision branches nested inside step 3, along with multi-paragraph prose in Store selection and Project check, create minor navigation friction that clearer headers or a trimmed structure would resolve. | 4 / 5 |
Total | 18 / 20 Passed |