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, highly actionable body with a clear sequenced workflow, explicit validation and confirmation checkpoints, and good failure handling for a destructive batch operation. Its weaknesses are redundancy across the four overlapping output templates and the absence of any progressive disclosure — everything, including lengthy examples, lives inline in SKILL.md.
Suggestions
Collapse step 9's example summary and the three "Output On ..." template sections into one canonical output section — the current duplication costs dozens of lines without adding information.
Move the Conflict Resolution Examples and output templates to a references/ file (e.g., references/conflict-examples.md) linked from the body, shortening SKILL.md to the workflow itself.
Replace the deferred "openspec-sync-specs approach" reference and the unspecified creation-date source with concrete steps (e.g., how to read change creation dates for chronological ordering) so every action is self-contained.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient with no explanation of concepts Claude already knows, but noticeably redundant: step 9's example summary duplicates the "Output On Success" and "Output On Partial Success" templates almost verbatim, and the Guardrails section re-states rules already given inline (e.g., "Always prompt for selection, never auto-select" repeats step 2's IMPORTANT). Not score 4 because the output-template duplication is a clear trim candidate; not score 2 because there is no padding or tutoring of known concepts. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: `openspec list --json`, `openspec status --change "<name>" --json`, task-counting via `- [ ]`/`- [x]`, requirement extraction pattern `### Requirement: <name>`, and copy-paste `mkdir -p`/`mv` archive commands. Not score 5 because step 8a defers spec sync to an unspecified "openspec-sync-specs approach" and chronological ordering depends on change creation dates without any command for obtaining them; not score 3 because nearly all steps are directly executable. | 4 / 5 |
Workflow Clarity | The batch/destructive operation is well served: a 9-step sequence with pre-flight validation (step 3), conflict detection (step 4), a consolidated status table before a single user confirmation (steps 6-7), per-change outcome tracking (success/skip/fail), and explicit failure isolation ("If archive target exists, fail that change but continue with others"). Not score 5 because there is no post-archive verification or validate-and-retry feedback loop (e.g., re-running `openspec list` to confirm, or validating spec sync results); not score 3 because validation checkpoints are explicitly present, so the batch-operation cap does not apply. | 4 / 5 |
Progressive Disclosure | Sections are well labeled (Steps, Conflict Resolution Examples, Output templates, Guardrails) but the ~235-line body is fully inline with no references/ bundle: the conflict-resolution examples and the three output template sections are content that would fit naturally in one-level-deep reference files. Not score 2 because structure is clear and navigation within the file is easy; not score 4 because no content is split out despite the length exceeding what the body alone should carry. | 3 / 5 |
Total | 14 / 20 Passed |