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 content is a tight, highly actionable instruction set: concrete paths, a real command, unambiguous merge rules, and a ready-to-use output format. The main gaps are the absence of any post-apply validation or verification step for what is a batch edit of multiple spec files, and a modest amount of duplication that could be trimmed.
Suggestions
Add an explicit validation step after applying deltas, e.g. re-read each updated main spec to confirm ADDED/MODIFIED requirements landed and preserved scenarios are intact, or run an openspec validate command if the CLI provides one.
Remove the opening line that repeats the frontmatter description, and fold redundant guardrail bullets into the step where each applies.
Consider moving the ~25-line 'Delta Spec Format Reference' block into a references/ file (e.g. references/delta-format.md) linked from the body, keeping SKILL.md as a leaner overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence throughout — it never explains what a spec or a delta is conceptually — and every section carries operational weight (paths, rules, output template). It is not a 5 because the opening line 'Sync delta specs from a change to main specs' duplicates the frontmatter description, and a few guardrail bullets could be tightened; it is well above anchor 3's 'some unnecessary explanation.' | 4 / 5 |
Actionability | Guidance is fully executable for an instruction-only skill: exact glob paths ('openspec/changes/<name>/specs/*/spec.md'), a runnable command ('openspec list --json'), a named tool (AskUserQuestion), deterministic per-section handling rules for ADDED/MODIFIED/REMOVED/RENAMED, a concrete format reference, and a copy-paste-ready output template. Specific examples cover the common cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | Steps 1-4 are clearly sequenced and include a stop checkpoint ('If no delta specs found, inform user and stop') plus read-before-edit guardrails. However, applying deltas is a batch operation across multiple spec files, and there is no post-apply verification step (no re-read of the merged spec, no 'openspec validate', no confirmation that preserved scenarios survived). Per the rubric, a batch operation without validation is capped at 3. | 3 / 5 |
Progressive Disclosure | There are no bundle files, and the single-file body is well organized with clearly headed, well-ordered sections; the inline 'Delta Spec Format Reference' is genuinely needed on every run. It does not reach 5 because the file runs ~125 lines — over the under-50-line threshold that earns a 5 for a self-contained skill — and the format reference and output template are candidates for a separate reference file. | 4 / 5 |
Total | 16 / 20 Passed |