openspec-sync-specs

Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

87%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is lean, highly actionable, and well-structured with concrete commands and format references for the merge operation. Its main gap is the absence of an explicit validation/verification checkpoint in a workflow that batch-edits main specs.

Suggestions

Add an explicit validation step after merging (e.g., run `openspec validate --change <name>` or re-run `openspec status --json`) with a fix-and-retry loop before showing the summary, since the workflow batch-edits main specs.

Note in the summary step how to verify the merged main spec retains the required single `## Requirements` structure with no leftover delta operation headers.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence with no concept padding; every section (commands, format references, guardrails) earns its place, including the two short markdown format-reference blocks that are directly required for the merge operation.	3 / 3
Actionability	Provides fully executable commands (e.g., `openspec status --change "<name>" --json`), specific JSON fields (`planningHome.root`, `artifactPaths.specs.existingOutputPaths`), concrete file paths, per-operation merge rules, and a copy-paste output template.	3 / 3
Workflow Clarity	The 5-step sequence (prompt → resolve context → find deltas → apply → summarize) is clearly ordered, but this batch/destructive spec-editing operation has no explicit validation or validate→fix→retry checkpoint; per the rubric, missing verification in such workflows caps clarity at 2.	2 / 3
Progressive Disclosure	A single self-contained file with well-signaled sections (Steps, Delta/Main Spec Format References, Key Principle, Output, Guardrails) and no nested multi-level references; content is appropriately organized for easy navigation with no bundle files needed.	3 / 3
	Total	11 / 12 Passed

Description

75%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concise and clearly answers both what the skill does and when to use it, with an explicit trigger clause and good distinctiveness from the archive operation. It could improve by enumerating multiple concrete actions and broadening natural trigger-term variations beyond OpenSpec jargon.

Suggestions

List multiple concrete actions (e.g., add, modify, remove, rename requirements) rather than a single 'sync' to lift specificity toward the top anchor.

Broaden the 'Use when' clause with natural variations users might say (e.g., 'merge changes into specs', 'apply a delta spec', 'sync specs') in addition to OpenSpec-specific terms.

Dimension	Reasoning	Score
Specificity	Names a concrete action ("Sync delta specs from a change to main specs") but lists a single operation rather than multiple distinct actions, matching the anchor that names a domain and some actions without being comprehensive.	2 / 3
Completeness	Explicitly answers both what ("Sync delta specs from a change to main specs") and when via a clear "Use when the user wants to update main specs with changes from a delta spec, without archiving the change" clause.	3 / 3
Trigger Term Quality	Includes relevant terms ("update main specs", "delta spec", "without archiving") but the coverage is narrow and leans on OpenSpec jargon, missing common variations like sync/merge/apply; not the broad natural-term coverage of the anchor-3 example.	2 / 3
Distinctiveness Conflict Risk	Occupies a clear OpenSpec niche (delta→main spec sync) and explicitly distinguishes itself from archiving ("without archiving the change"), making conflict with other skills unlikely.	3 / 3
	Total	10 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: Fission-AI/OpenSpec
Path: skills/openspec-sync-specs/SKILL.md
Commit: 19d4171

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.