Content
78%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, actionable procedural skill: concrete CLI commands, explicit user-confirmation checkpoints, defined failure handling for the archive-collision case, and proper delegation of sync logic. Remaining weaknesses are minor — a redundant guardrails section, an underspecified delta-spec comparison method, and no post-move verification.
Suggestions
Trim the Guardrails section to only non-duplicative rules (e.g. 'Preserve .openspec.yaml' and 'Don't block archive on warnings') since several bullets restate step 1 and step 4 verbatim.
Give step 4 a concrete comparison method — e.g. a command or explicit diff procedure for matching delta specs against 'openspec/specs/<capability>/spec.md' — so the sync assessment is executable rather than descriptive.
Add a post-archive verification step (confirm the moved directory exists at 'openspec/changes/archive/YYYY-MM-DD-<name>' and the source is gone) and specify behavior if a requested sync fails before proceeding to archive.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a lean procedural document with concrete commands and no explanation of concepts Claude already knows. Not a 5 because the Guardrails section restate content already specified in steps (e.g. 'Always prompt for change selection if not provided' repeats step 1's IMPORTANT note; 'If delta specs exist, always run the sync assessment...' repeats step 4); not a 3-adjacent lower score because the redundancy is minor and the rest is efficient. | 4 / 5 |
Actionability | Mostly executable guidance: concrete commands ('openspec list --json', 'openspec status --change "<name>" --json', 'mkdir -p openspec/changes/archive', 'mv openspec/changes/<name> ...'), concrete paths, parsed JSON fields, and a copy-paste output template. Not a 5 because step 4's delta-spec comparison ('Compare each delta spec with its corresponding main spec... Determine what changes would be applied') is high-level direction with no concrete comparison method or command. | 4 / 5 |
Workflow Clarity | A clear 6-step sequence with explicit validation checkpoints: artifact status check, task-file check, user confirmations via AskUserQuestion, and a pre-move existence check with defined failure handling ('Fail with error, suggest renaming'). Not a 5 because there are minor gaps — no verification that the 'mv' succeeded, and the archive proceeds regardless of whether the delegated sync actually succeeded. | 4 / 5 |
Progressive Disclosure | A single self-contained skill file, clearly sectioned (Input, Steps, Output On Success, Guardrails) with easy navigation and no inlined content that belongs in a separate file. Sync execution is properly delegated to the openspec-sync-specs skill — a well-signaled one-level-deep reference — and no bundle files exist to score against, so nothing is buried or nested. | 5 / 5 |
Total | 17 / 20 Passed |