Content
82%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, highly actionable workflow skill: concrete CLI commands, explicit branch handling, one-artifact-per-invocation guardrails, and a verification checkpoint. Weaknesses are minor — some duplicated guardrail text, no error-recovery loops, and a small amount of content that duplicates CLI-provided details.
Suggestions
Consolidate the duplicated 'context and rules are constraints for YOU' guidance into the Guardrails section only, and drop the opening line that restates the description to tighten conciseness.
Add a short error-recovery loop for the write/verify step (e.g., if the artifact file is missing after writing or the status JSON fails to parse, re-check and retry once before reporting to the user) to close the workflow-clarity validation gap.
Trim or compress the 'Common artifact patterns' section since the CLI's 'instruction' field already provides schema-specific guidance per artifact.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient — concrete CLI commands with JSON field semantics, no explanations of concepts Claude already knows. Minor trimming opportunities exist: the 'context and rules are constraints for YOU' guidance appears twice (in step 3 and again in Guardrails), and the opening line restates the description verbatim. This fits the efficient-with-minor-over-explanation anchor, not the lean every-token-earns-its-place anchor. | 4 / 5 |
Actionability | Fully executable guidance: copy-paste ready commands ('openspec list --json', 'openspec status --change "<name>" --json', 'openspec instructions <artifact-id> --change "<name>" --json'), explicit parsing of the returned JSON fields, concrete artifact patterns per schema, and clear output requirements. Specific examples cover the common cases (no name given, all complete, ready artifacts, all blocked). | 5 / 5 |
Workflow Clarity | The sequence is clear and unambiguous: select change → check status → branch on isComplete/ready/blocked → create one artifact → show progress, with an explicit validation checkpoint ('Verify the artifact file exists after writing before marking progress') and a guardrails checklist. It falls short of the top anchor because there are no error-recovery feedback loops — nothing on what to do if the status JSON is malformed, the write fails, or verification fails — though the explicit verification step keeps it above the missing-checkpoints anchor. | 4 / 5 |
Progressive Disclosure | A single-file skill with no bundle directories (no references/, scripts/, or assets/) and none needed — details are delegated to the CLI's instructions output, which is good design. Sections are well-organized and appropriately sized, but the 'Common artifact patterns' section partially duplicates what the CLI's 'instruction' field already supplies, a minor placement gap that keeps it below the top anchor. | 4 / 5 |
Total | 17 / 20 Passed |