Content
67%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-validated workflow whose main cost is prose density: several passages pack nested edge cases into single run-on sentences that require multiple readings. Validation checkpoints are genuinely strong (path-safety checks, one-artifact-per-invocation guardrail, disk re-reads), and structure is solid for a single-file skill.
Suggestions
Break the Store selection paragraph and the partly-written-artifact bullet into short bulleted rules or a small table so each edge case is one scannable line.
Move the root/store troubleshooting detail (config.yaml store declaration errors, sticky --store mechanics) into a reference file and keep a one-line pointer in SKILL.md.
Add a brief worked example of one status->instructions->create cycle to make the happy path fully concrete.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense with no teaching of concepts Claude already knows, but several sections are noticeably tangled — the Store selection paragraph and the ~150-word single-sentence partly-written-artifact bullet repeat logic and need tightening to be efficient. | 3 / 5 |
Actionability | Concrete executable commands ("openspec status --change \"<name>\" --json", "openspec instructions <artifact-id> ...") with enumerated JSON fields and explicit decision branches, but there is no worked example of a created artifact and several steps resolve to "ask the user" or fully depend on runtime CLI output, leaving minor gaps. | 4 / 5 |
Workflow Clarity | A clear numbered sequence with status-based branching, explicit validation (verify the file exists, path-inside-changeRoot checks, re-read dependencies from disk), and a guardrails checklist, but the pre-steps (store/project check) precede the Steps section and the convoluted glob-artifact recovery logic muddies step 3's internal sequence. | 4 / 5 |
Progressive Disclosure | A single-file skill with no bundle files whose content is core workflow logic that reasonably lives inline; sections are clearly organized (Store selection, Project check, Input, Steps, Output, Guardrails), though the long store/project-check detours could arguably be split into a reference file. | 4 / 5 |
Total | 15 / 20 Passed |