Content
63%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 strong, concrete operational workflow: sequenced steps, explicit commands, a confirmation gate before the destructive batch operation, conflict-resolution logic with worked examples, and per-change failure handling. The main weaknesses are redundancy between the summary and output sections, an underspecified spec-sync sub-step, and no offloading of examples/templates into reference files.
Suggestions
Consolidate the step 9 summary example with the "Output On Success/Partial Success" sections into one set of output templates, and trim the redundant intro sentence and guardrails that restate steps.
Specify the spec-sync step concretely (or point to the openspec-sync-specs skill file path) and add a post-archive verification such as checking `openspec/changes/archive/YYYY-MM-DD-<name>` exists before marking success.
Move the two conflict-resolution examples and the output templates into a `references/` file (e.g. `references/examples.md`) with clear pointers from the body to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is operational rather than explanatory, but includes padding: the intro sentence ("This skill allows you to batch-archive changes, handling spec conflicts intelligently...") restates the title, step 9's summary example duplicates the "Output On Success/Partial Success" templates, and several guardrails restate earlier steps. This fits 'mostly efficient but could be tightened' rather than the minor-trimming anchor at 4. | 3 / 5 |
Actionability | Concrete, executable guidance throughout — `openspec list --json`, `openspec status --change "<name>" --json`, task-counting on `- [ ]`/`- [x]`, requirement extraction via `### Requirement: <name>`, and copy-ready `mkdir -p`/`mv` commands plus table and output templates. Minor gaps keep it at 4: step 8a defers to "the openspec-sync-specs approach (agent-driven intelligent merge)" without detail, and step 5b's "search the codebase for implementation evidence" is underspecified. | 4 / 5 |
Workflow Clarity | The 9 steps are clearly sequenced with checkpoints (early stop when no changes, status gathering, conflict map, consolidated status table, user confirmation gate, per-change outcome tracking, and failure recovery via "fail that change but continue with others"), so the batch-operation cap at 3 does not apply. Not 5 because there is no post-archive verification of the moved directory and the spec-sync sub-step lacks its own validation loop. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned and navigable, but there are no bundle files at all while roughly 80 lines of conflict-resolution examples and output templates would naturally live in a one-level-deep reference file; the only external pointer is to another skill (openspec-sync-specs) rather than to bundled material. This matches 'some structure but content that should be separate is inline' rather than anchor 2, since the inlined material directly supports the core workflow. | 3 / 5 |
Total | 14 / 20 Passed |