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.
A disciplined, high-clarity CLI workflow: commands are concrete, the sequence is explicit, and destructive operations are guarded with validation and recovery paths. The weaknesses are redundancy (the Guardrails section repeats in-step rules) and a monolithic single-file structure with an unbundled external workflow dependency at its center.
Suggestions
Trim the Guardrails section to rules not already stated in the steps — several entries ('Never archive while a spec sync is still in flight', 'If sync is requested, run the openspec-sync-specs workflow inline') duplicate step 4 verbatim, which costs tokens without adding safety.
Move the detailed post-sync structural contract in step 4 (title, Purpose, requirement/scenario heading rules) into a bundled reference file and link it one level deep, keeping only the verification checklist inline.
Give the 'openspec-sync-specs' workflow a concrete path or bundle reference so the delegated sync step is executable from this skill's own files rather than assumed to exist.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body mostly earns its tokens with non-obvious CLI contracts, but is noticeably tightenable: the Guardrails section restates rules already given in the steps ('Never archive while a spec sync is still in flight', 'If sync is requested, run the openspec-sync-specs workflow inline', 'Apply relevant runtime context and report conflicts'), and the store-selection and context/guidance paragraphs are convoluted. Matches anchor 3 ('mostly efficient but... could be tightened') rather than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Guidance is largely executable: exact commands ('openspec instructions archive --change "<name>" --json', 'openspec status --change "<name>" --json', 'mkdir -p "<planningHome.changesDir>/archive"', 'mv "<changeRoot>" ...'), named JSON fields to parse, and a precise date-prefix rule. The minor gap is that the core sync step delegates to an 'openspec-sync-specs' workflow that is not bundled or pathed, so that portion cannot be executed from this file alone — anchor 4, not 5. | 4 / 5 |
Workflow Clarity | Six clearly numbered steps with explicit validation checkpoints and feedback loops around destructive operations: artifact-status and task-count checks with user confirmation, strict post-sync structural verification with stop conditions, an existence check before the 'mv', and error-recovery guidance ('report what differs and stop — do not archive. Nothing has moved... the user can fix the mismatch or re-run the sync'). This matches anchor 5. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), so all content lives inline in one ~210-line file. Sections are clearly marked (Steps, Output On Success, Guardrails), but content that could plausibly be split out (the sync structural contract, store-selection rules, project-check branching) is inlined, and the external 'openspec-sync-specs' workflow reference has no path. Anchor 3: 'some structure but could be better organized' — not 4 because the split-out opportunity is more than minor. | 3 / 5 |
Total | 15 / 20 Passed |