Content
68%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 body that clearly sequences the sync workflow with concrete commands, paths, and output formats. Its main gap is the absence of a post-edit verification step for a batch, partly destructive operation on main spec files.
Suggestions
Add an explicit verification step after applying changes (e.g., re-read each updated main spec to confirm structure, or run an openspec validation command) to close the validation gap for this batch-edit workflow.
Trim redundancy: drop the opening line that repeats the frontmatter description and let the Delta Spec Format Reference carry the section-handling details already covered in step 3c.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is focused procedural guidance with no padding or explanation of concepts Claude already knows; minor tightening is possible since the opening line "Sync delta specs from a change to main specs." duplicates the frontmatter description and the step 3c rules partially restate the format reference. | 4 / 5 |
Actionability | Concrete guidance throughout: the exact command `openspec list --json`, precise paths like `openspec/changes/<name>/specs/*/spec.md`, per-section handling rules, a worked delta-format example, and a copy-ready output template; minor gaps remain (no command to verify results, and merging depends on judgment calls like "Use your judgment to merge changes sensibly"). | 4 / 5 |
Workflow Clarity | Steps 1-4 are clearly sequenced with pre-checks ("If no delta specs found, inform user and stop") and guardrails ("Read both delta and main specs before making changes"), but this batch edit of spec files — including destructive REMOVED Requirements — has no post-edit validation or verification step, capping the score at 3 per the batch/destructive guideline. | 3 / 5 |
Progressive Disclosure | As a single-file skill with no bundle, its well-organized sections (Steps, Delta Spec Format Reference, Output On Success, Guardrails) keep content appropriately placed; at ~128 lines it exceeds the under-50-line exception, and the format reference block could arguably live in a separate file, so it stops short of anchor 5. | 4 / 5 |
Total | 15 / 20 Passed |