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 well-structured, largely executable instruction skill: clear sequencing, explicit validation requirements, and a real externalized installer script. The main gaps are the absence of an explicit validate-fail-retry feedback loop and isolated prose redundancy in the NVM section.
Suggestions
Add an explicit feedback loop after validation (e.g., 'If openspec validate fails, fix the cited artifacts and re-run before proceeding to the next task') to raise workflow_clarity.
Tighten the CLI Runtime Resolution section: the 'Do not conclude...' paragraph largely restates the resolution sequence, so trim it to the one non-obvious signal (~/.agents/bin/openspec reporting 'env: node: No such file or directory').
Reference the installer with its bundle-relative path (scripts/install-openspec) in addition to the shared ~/.agents path so the bundle structure is self-evident.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with tool-specific guidance (NVM resolution sequence, installer placement policy, OPSX workflow) and avoids explaining concepts Claude already knows, but the NVM section restates its own code twice — 'Do not conclude that OpenSpec is unavailable merely because it is absent from the initial PATH' repeats what the resolution sequence already demonstrates — and the symlink path explanation appears in two sections. Not level 5 because every token does not earn its place; not level 3 because the padding is isolated to a few sentences rather than whole sections. | 4 / 5 |
Actionability | Provides copy-paste bash for NVM resolution, installer invocation, and CLI state/validation commands ('openspec list', 'openspec validate --all'), plus a fallback ('perform the same workflow directly in files under openspec/changes/<change>/') for tools without slash commands. Not level 5 because several workflow steps remain directive rather than executable ('Explore unclear requirements before creating artifacts', 'Review and refine proposal.md, delta specs, design.md, and tasks.md') with no examples of well-formed artifacts. | 4 / 5 |
Workflow Clarity | The Default Workflow is a clear six-step sequence (explore, propose, review, apply tasks one at a time, verify against proposal/specs/design/tasks, sync and archive) with explicit validation mandated in Artifact Standards ('Run OpenSpec validation and the repository's canonical validation before claiming completion'). Not level 5 because there is no error-recovery feedback loop (nothing says what to do when validation fails or a task check reveals a defect); not level 3 because checkpoints are explicit rather than implicit. | 4 / 5 |
Progressive Disclosure | The single bundle file (scripts/install-openspec) is appropriately externalized and the ~107-line body is organized into clear, well-scoped sections with no content that clearly belongs in a separate file. Not level 5 because the installer is referenced via the shared '~/.agents/skills/openspec/scripts/install-openspec' path rather than a clearly signaled relative bundle path, and the machine-specific NVM detail could live in a reference file. | 4 / 5 |
Total | 16 / 20 Passed |