Content
85%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 an exceptionally actionable, well-sequenced workflow with explicit commands, validation checkpoints, and error-recovery loops. Its main weaknesses are a monolithic single-file structure with no progressive disclosure of dense reference material, and some duplicated statements that could be trimmed.
Suggestions
Move the store-selection semantics and the required-set/dependency-walk rules (step 5b) into a reference file (e.g. references/store-selection.md), keeping SKILL.md to the core workflow.
Deduplicate the planning-boundary statement and the re-read-from-disk rule, each of which appears both in the body and again in the Guardrails section.
Tighten the store-selection paragraph, which is the wordiest section and repeats the --store flag instructions given later in step 3.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and operational with no explanations of concepts Claude already knows, but there is repetition to trim: the planning boundary is stated in both the opening paragraph and Guardrails, the re-read-from-disk rule appears in step 5a and Guardrails, and the store-selection paragraph is wordy. Efficient with minor instances of over-explanation fits 4; not 5 because of this duplicated content. | 4 / 5 |
Actionability | Every step has copy-paste-ready commands with exact flags (openspec new change "<name>" --schema "<schema-name>", openspec status --change "<name>" --json, openspec instructions <artifact-id> --change "<name>" --json), the JSON fields to parse are named, and the user prompts and progress strings are given verbatim. Fully executable guidance covering the common cases matches the 5 anchor. | 5 / 5 |
Workflow Clarity | A clear 6-step sequence with explicit validation checkpoints (re-run openspec status --json after each artifact; "Verify each artifact file exists after writing before proceeding to next"), feedback loops for error recovery (skipped/blocked/missing artifact handling, user-clarification loop), todo-list tracking, and explicit stop conditions. This matches the 5 anchor; not 4 because no validation checkpoint is missing. | 5 / 5 |
Progressive Disclosure | A single ~137-line SKILL.md with no bundle files: it is well-sectioned with clear headers, but dense inline content (store-selection semantics, the required-set/dependency-walk rules in step 5b) sits in SKILL.md rather than being split into reference files. Some structure but content that should be separate is inline fits 3; not 4 because there are no references and separable content is inlined, not 2 because the structure is good and navigable. | 3 / 5 |
Total | 17 / 20 Passed |