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 delivers a highly actionable, well-sequenced CLI workflow with strong validation feedback loops, but it is noticeably redundant - the same rules on pausing, context/guidance handling, and completion are repeated across steps, guardrails, and output templates. It is also a long monolithic file with no reference files despite clearly splittable content like the output templates.
Suggestions
Deduplicate the guardrails section against the pause conditions in step 6 and the context/operationGuidance rules in steps 3-4 - each rule is currently stated two to three times; state each once in the step where it applies and keep the guardrails to non-duplicated invariants.
Tighten the store-selection paragraph: lead with the single rule (pass --store <id> on reads/writes once selected, keep it sticky) and trim the restated examples and command enumerations.
Move the three full output templates (Implementing / Complete / Paused) into a references/output-templates.md file and reference it one level deep, keeping SKILL.md to the workflow itself.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The pause conditions, the context/operationGuidance handling rules, and the 'review before archiving' note are each stated two to three times across steps 3-4, the guardrails, and the output templates, and the store-selection paragraph is a dense padded wall of conditionals. This matches anchor 2 ('several unnecessary explanations or padded sections') rather than 3, since the duplication is systematic rather than occasional over-explanation. | 2 / 5 |
Actionability | Copy-paste-ready commands (`openspec status --change "<name>" --json`, `openspec instructions apply --change "<name>" --json`), specific JSON fields to parse (schemaName, contextFiles, sourcePath, line), and an exact edit instruction (`- [ ]` to `- [x]`) make the guidance fully executable. Not 4 because the concrete commands and field-level parsing cover the common cases without gaps. | 5 / 5 |
Workflow Clarity | A clear 7-step sequence with explicit validation checkpoints and feedback loops: confirm the checkbox at sourcePath/line before editing, rerun apply instructions after marking, and confirm progress changed; pause conditions and blocked/all_done state handling are enumerated. This matches anchor 5; anchor 4 would require missing checkpoints, which are present. | 5 / 5 |
Progressive Disclosure | The steps are organized with headers, but this is a ~195-line single file with no bundle references at all, and content that could be split out is inlined (three full output templates, the store-selection and project-check prose). This fits anchor 3 ('could be better organized; content that should be separate is inline'); it is not 2 because structure is real and coherent, and not 4 because nothing is offloaded and the file is well over the simple-skill threshold. | 3 / 5 |
Total | 15 / 20 Passed |