Content
75%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 highly actionable, well-sequenced workflow with strong validation checkpoints and unambiguous commands. Its main weakness is token efficiency: several guardrails are stated two or three times and key sections are written as hard-to-parse run-on sentences that a single tightened pass would fix.
Suggestions
State the "instruction field delegates to a skill or command" rule once (e.g., in the Artifact Creation Guidelines section) and reference it from the two workflow steps instead of repeating the full caveat three times.
Split the store-selection paragraph and the 'finish a partly written artifact' section into short imperative bullets; each is currently a single 80+ word sentence that buries the path-safety check and ONE-artifact rule.
Merge the duplicate symlink/changeRoot path-verification instructions (step 3's partly-written-artifact branch and the create-artifact branch) into one shared 'path safety' checklist item, and fold the repeated 're-read dependencies from disk' guidance into the Guardrails section only.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is densely operational with no concept explanations Claude already knows, but it is noticeably repetitive and could be tightened: the "instruction field delegates to a skill or command" rule appears three times, the symlink/changeRoot path check twice, and "re-read dependencies from disk" twice, while the store-selection paragraph and the partly-written-artifact section are single run-on sentences of 80+ words. It is above anchor 2 because the verbosity is redundant guardrails rather than padded explanation. | 3 / 5 |
Actionability | Commands are copy-paste ready (`openspec status --change "<name>" --json`, `openspec instructions <artifact-id> --change "<name>" --json`, `openspec list --json`), with field-by-field JSON parsing guidance and explicit branch handling covering the common cases, matching the 'fully executable' anchor for an instruction-only skill. | 5 / 5 |
Workflow Clarity | The four-step sequence is clear with status-based branching, explicit validation checkpoints (verify the file exists after writing, check `root` before any write, path-inside-changeRoot checks), and error-recovery loops (stop and tell the user, ask when uncertain). It falls short of anchor 5 because the partly-written-artifact branch's convoluted nested prose makes its checkpoints hard to follow in order. | 4 / 5 |
Progressive Disclosure | With no bundle files, all content is appropriately inline for a self-contained CLI workflow, organized under clear section headers (Store selection, Project check, Input, Steps, Output, Guardrails). It is below anchor 5 because at ~125 lines the long store-selection and error-branch prose could be split or trimmed, leaving minor organization gaps rather than a clean overview. | 4 / 5 |
Total | 16 / 20 Passed |