Content
70%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.
The body is exceptionally actionable — exact CLI commands, JSON fields to read, validation loops, and worked conversation examples — with strong workflow sequencing and error-recovery checkpoints. Its weaknesses are token efficiency (the store-scoping and confirmation rules each repeated three-plus times, and one ~350-word single-paragraph step) and progressive disclosure (345 lines inlined in one file with no reference files).
Suggestions
State the sticky --store rule once in the Store selection section and refer back to it (e.g. 'apply the sticky --store rule') instead of repeating the parenthetical verbatim in capture steps 2, 3, and 4.
Break the ~350-word step 2 of the capture transition into a short bulleted list of sub-rules, and deduplicate the write-confirmation rules stated in the intro, 'Keep a conversational record', and the 'Don't auto-capture' guardrail into one authoritative statement.
Move the four 'Handling Different Entry Points' dialogue examples (and optionally the capture-transition procedural detail) into a references/ file linked from a brief section, shortening SKILL.md and improving progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Noticeably verbose: the sticky `--store` rule is stated once in the Store selection section, then the parenthetical "(append the confirmed `--store "<id>"` only for a registered standalone store)" is repeated verbatim in capture steps 2, 3, and 4; the write-confirmation rule appears in the intro paragraph, in "Keep a conversational record", and again in "Don't auto-capture"; and capture step 2 is a single ~350-word paragraph of nested conditionals. This matches anchor 2's 'several unnecessary explanations or padded sections' rather than anchor 3's 'some' tightening opportunities — though it never explains concepts Claude already knows, so it stays above anchor 1. | 2 / 5 |
Actionability | Fully executable, copy-paste-ready commands throughout: `openspec list --json`, `openspec status --change "<name>" --json`, `openspec instructions "<artifact-id>" --change "<name>" --json`, plus concrete JSON fields to read (`root`, `changeRoot`, `artifactPaths`, `resolvedOutputPath`), a spec rules/config reading procedure, an insight-to-artifact capture table, and worked dialogue examples for four common entry points. Matches anchor 5's 'specific examples cover the common cases'. | 5 / 5 |
Workflow Clarity | Sequences are explicit with validation and feedback loops: the project check (run `openspec list --json` and read `root`; treat a non-zero exit as the answer, not a broken CLI), the capture loop ("After creating each artifact, re-run `openspec status --change \"<name>\" --json` ... and continue until every requested artifact is `done`, `skipped`, or was deliberately skipped"), output-path verification inside `changeRoot` after resolving symlinks, "Verify that the selected concrete output exists", and error-recovery guidance (show the error's `message` and `fix` for store declaration errors). Matches anchor 5; anchor 4's 'minor validation gaps' does not apply. | 5 / 5 |
Progressive Disclosure | Sections are clearly headed (The Stance, Planning a Change, OpenSpec Awareness, Handling Different Entry Points, Guardrails), but the skill is a single ~345-line file with no bundle files at all — long procedural detail (the capture-transition steps) and four multi-line dialogue examples are inlined where a shorter SKILL.md pointing to one-level-deep reference files would navigate better. This sits between anchor 2 ('content that clearly belongs in separate files is inlined' but that anchor assumes minimal structure) and anchor 4 (appropriate placement), landing on anchor 3. | 3 / 5 |
Total | 15 / 20 Passed |