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 dense, disciplined workflow document: every CLI interaction is given as a concrete command, the six-step sequence has real validation and confirmation checkpoints (including a re-verify loop before creating any file), and it consistently encodes non-obvious CLI semantics rather than general knowledge. The main weaknesses are mild: Guardrails repeat rules already stated in the steps, the store-selection paragraph is a wall of conditions, and the glob-creation sub-procedure inlines detail that could live in a one-level-deep reference file.
Suggestions
Tighten the store-selection paragraph into a short bulleted rule list (when to pass --store, which commands take it, stickiness) — it currently reads as one long run-on sentence chain and is the hardest part of the body to follow.
Deduplicate the Guardrails section: rules like 'never write to a glob resolvedOutputPath' and 'do not advance the build frontier' already appear verbatim in steps 2, 4, and 6; keep Guardrails to the one-line 'planning artifacts only, never code' rule and the update-vs-start-fresh heuristic.
Give one concrete check for the symlink-resolution requirement in step 4 (e.g., an explicit realpath/test command) and a one-line example of what a proposed revision presented to the user should look like, since those are the only places the guidance is abstract.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every token is non-obvious operational knowledge Claude could not infer (glob vs. resolved output paths, '"root": null' exit-code semantics, sticky --store flag), which is the ideal use of a skill body. What keeps it below 5 is repetition and wordiness: the Guardrails section restates rules already established in steps 2, 4, and 6 ('never write to a glob resolvedOutputPath', 'do not advance the build frontier'), and the store-selection paragraph packs several rules into one long run-on explanation that could be tightened. Not 3: there is no explanation of concepts Claude already knows, and the padding is minor relative to the density of real guidance. | 4 / 5 |
Actionability | Concrete, executable commands with placeholders are given for every CLI interaction ('openspec status --change "<name>" --json', 'openspec instructions "<artifact-id>" --change "<name>" --json', 'openspec list --json'), along with the exact JSON fields to read ('existingOutputPaths', 'isPlanningComplete', 'lastModified') and a concrete option-presentation format for prompting. It falls short of anchor 5 because the core edit step itself is described abstractly ('Draft the requested edit in the conversation') and 'choose a concrete path... after resolving any symlinked parent directories' gives no command or check to perform that resolution. Not 3: the guidance that exists is fully executable, not pseudocode. | 4 / 5 |
Workflow Clarity | Six clearly numbered steps in a coherent order, with explicit validation checkpoints throughout: pre-flight project check via 'openspec list --json' and 'root', confirmation gates before every write, and a full re-verification loop before file creation (refresh status and instructions, re-check scope/skip/partial state, use a create that 'fails if the target already exists', stop and reconcile on failure). Error recovery is handled explicitly for both the 'root: null' and 'Declared in' error cases. This matches the anchor with explicit validation steps and feedback loops, which matters here since artifact writes are user-confirmed and partially destructive. | 5 / 5 |
Progressive Disclosure | This is a single-file skill (no references/, scripts/, or assets/ exist), and the body is organized into well-labeled, easy-to-navigate sections (Store selection, Project check, Input, numbered Steps, Output, Guardrails) with no nested-reference indirection. It misses anchor 5 because the ~100-line body inlines two dense procedural blocks — the 5-step glob-file creation sub-procedure in step 4 and the store-selection rules — that read like shared reference material (near-identical rules would apply to the sibling OpenSpec workflows this body cross-references) and could be split into one-level-deep reference files. Not 3: nothing is buried or unmarked, and the inline content is all genuinely used by this workflow. | 4 / 5 |
Total | 17 / 20 Passed |