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 thorough, well-sequenced batch workflow with genuinely strong operational detail: exact CLI commands, file paths, conflict-resolution heuristics, confirmation gates, and per-change failure handling. Its weaknesses are redundancy (three near-duplicate output templates plus a guardrails section restating inline rules) and a fully monolithic layout where conflict examples and output formats could be split into reference files.
Suggestions
Collapse the duplicated output templates (step 9 summary, "Output On Success", "Output On Partial Success") into one parameterized template, and trim Guardrails items that literally repeat inline step text.
Move the two conflict-resolution examples and the output-format specifications into a references/ file (e.g. references/conflict-examples.md) and link to them, keeping SKILL.md as the overview plus steps.
Inline a short, concrete recipe for the spec-sync merge in step 8a (or point to a specific script/section) instead of deferring vaguely to "the openspec-sync-specs approach".
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly concrete instruction, but there is real duplication beyond minor: step 9's summary template, "Output On Success", and "Output On Partial Success" repeat nearly identical output formats, and the Guardrails section restates inline rules ("Always prompt for selection, never auto-select" repeats step 2's "Do NOT auto-select"). This fits 'mostly efficient but could be tightened'; it is not 2 because nothing explains concepts Claude already knows. | 3 / 5 |
Actionability | Guidance is largely executable: exact commands (`openspec list --json`, `openspec status --change "<name>" --json`), exact paths and parsing patterns (`openspec/changes/<name>/tasks.md`, `### Requirement: <name>`), and concrete mv commands with a date format. It stops short of 5 because step 8a defers to "the openspec-sync-specs approach (agent-driven intelligent merge)" with no inline detail, and step 5b's "Search the codebase for implementation evidence" is open-ended. | 4 / 5 |
Workflow Clarity | Nine well-sequenced steps with explicit checkpoints for a batch/destructive operation: pre-flight batch validation (step 3), conflict detection before any mutation (steps 4-5), user confirmation before destructive moves (steps 2 and 7), per-change outcome tracking (step 8c), and failure containment ("If archive target exists, fail that change but continue with others"). Validation is present, so the batch-operation cap of 3 does not apply; it is not 5 because there is no post-move verification and the sync step leans on an external approach. | 4 / 5 |
Progressive Disclosure | The skill is a single ~250-line file with no bundle (no references/, scripts/, or assets/ exist) and no external references at all. Section headers make it navigable, but content that would fit a reference file — the two full conflict-resolution examples (Example 1/Example 2) and the repeated output templates — is inlined, matching 'some structure but content that should be separate is inline'. It is not 2 because the file is well-sectioned and self-contained rather than a monolithic wall. | 3 / 5 |
Total | 14 / 20 Passed |