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, lean instruction-only skill with concrete CLI commands, explicit user-confirmation checkpoints around a destructive move, and a clear output template. The gaps are small: a couple of high-level directives without a method, no post-archive verification, and mild duplication between the steps and the Guardrails section.
Suggestions
Add a post-move verification step (e.g. confirm openspec/changes/archive/YYYY-MM-DD-<name> exists and openspec/changes/<name> is gone) with a recovery path, which would lift workflow_clarity to 5.
Specify how to compare delta specs with main specs (e.g. which sections to diff or an example) so step 4 is as executable as the rest.
Trim the Guardrails bullets that restate step instructions and keep only the ones adding new information (e.g. the .openspec.yaml preservation note).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body gives commands and paths directly ("openspec list --json", "mkdir -p openspec/changes/archive") with no explanation of concepts Claude already knows; the only trimmable material is the Guardrails section restating rules already in the steps ("Always prompt for change selection if not provided"), which is minor duplication fitting the efficient-with-minor-trims anchor at 4 rather than the noticeable-verbosity anchor at 3. | 4 / 5 |
Actionability | Concrete executable commands with literal paths ("openspec status --change \"<name>\" --json", "mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>"), explicit task-marking syntax ("- [ ]" vs "- [x]"), and a copy-paste output template cover the common cases; a few directives stay high-level ("Compare each delta spec with its corresponding main spec" gives no comparison method), keeping it below fully-executable at 5. | 4 / 5 |
Workflow Clarity | Six clearly numbered steps with explicit confirmation checkpoints (AskUserQuestion for selection, for incomplete artifacts, for incomplete tasks, and a three-option sync prompt) plus a target-exists failure check give this destructive move operation most of its checkpoints; it falls short of 5 because there is no post-move verification that the archive succeeded and no error-recovery loop for the mv step. | 4 / 5 |
Progressive Disclosure | The file is cleanly sectioned (Input / Steps / Output On Success / Guardrails) and correctly delegates sync detail to the openspec-sync-specs skill, a clearly signaled one-level reference; no bundle files exist and nothing clearly needs splitting, but at ~105 lines with some step-level detail that could live elsewhere it fits 'good structure; minor organization gaps' at 4 rather than the well-split anchor at 5. | 4 / 5 |
Total | 16 / 20 Passed |