Content
76%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.
The body is a well-structured, highly actionable instruction skill: exact paths, a concrete command, complete per-operation handling, and a copy-paste output template. Its main gaps are the absence of an explicit validation/verification checkpoint with an error-recovery loop for what is a batch, partially destructive operation, and mild redundancy between the format reference, the Key Principle section, and Step 3c.
Suggestions
Add an explicit validation step after applying changes (e.g., re-read each updated main spec to confirm every delta was applied and the file is well-formed) with a feedback loop for error cases such as a MODIFIED or RENAMED requirement not found in the main spec.
Consolidate the 'Key Principle: Intelligent Merging' section into Step 3c and trim or shorten the Delta Spec Format Reference, since both partially duplicate guidance already given in the apply-changes step.
Specify behavior when the same requirement appears in both ADDED and MODIFIED sections, or when a delta references a capability whose main spec has a Purpose that conflicts, to remove the remaining execution ambiguity.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and assumes Claude's competence (no concept explanations, no padding), but the 25-line Delta Spec Format Reference and the 'Key Principle: Intelligent Merging' section partially repeat details already covered in Step 3c and could be trimmed or merged, matching the 'minor instances of over-explanation' anchor. | 4 / 5 |
Actionability | Guidance is fully executable: exact file paths (openspec/changes/<name>/specs/*/spec.md, openspec/specs/<capability>/spec.md), a concrete CLI command (openspec list --json), explicit per-operation handling for all four delta section types, new-spec creation instructions, and a copy-paste output template covering the common cases. | 5 / 5 |
Workflow Clarity | Steps 1-4 are clearly sequenced with read-before-write guardrails and a final summary, but this is a batch edit of multiple spec files including destructive REMOVED requirements, and there is no explicit validation checkpoint or error-recovery loop (e.g., what to do when a MODIFIED requirement is not found in the main spec, or verifying main specs after applying). Per the rubric cap for batch/destructive operations lacking validation, the score is capped at 3 even though sequencing is otherwise strong. | 3 / 5 |
Progressive Disclosure | The single-file body is well organized into clearly signaled sections (Steps, format reference, output template, guardrails) with no nested references and no bundle files, matching the 'good structure, minor organization gaps' anchor; the skill exceeds 50 lines and its inline format reference is the one candidate for a separate reference file, keeping it below anchor 5. | 4 / 5 |
Total | 16 / 20 Passed |