openspec-sync-specs

Sync delta specs from an OpenSpec change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change. Also use when the user says "openspec sync" or "opsx sync".

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/openspec-sync-specs/SKILL.md

Quality

Content

77%Weight 40%Scale 1-5

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

An exceptionally actionable, well-sequenced procedural skill with strong validation and safety guardrails around destructive spec operations. Its weaknesses are redundancy across steps and a monolithic single-file structure that inlines reference material better kept in separate bundle files.

Suggestions

Deduplicate repeated rules (empty Requirements section, retirement conditions, narrowed-selection handling) into one authoritative statement and reference it from the Guardrails checklist instead of restating steps verbatim.

Move the Delta Spec Format Reference, Main Spec Format Reference, and the six retirement conditions into a references/ file (e.g., references/format.md, references/retirement.md) and link them from SKILL.md to reduce context load for routine syncs.

Trim the store-selection preamble by moving the sticky-flag mechanics into the Guardrails section or a reference file, keeping only the store-detection instruction inline.

Dimension	Reasoning	Score
Conciseness	The body is dense with non-obvious operational knowledge (CLI flags, JSON fields, archive-matching semantics) and does not pad with concepts Claude already knows, but it repeats itself noticeably: "Never write an empty ## Requirements section" appears twice, retirement conditions are restated across steps 4c and 4d, and the Guardrails section restates earlier steps verbatim. It fits "mostly efficient but could be tightened" rather than the minor-trim anchor.	3 / 5
Actionability	Fully executable throughout: exact commands ("openspec status --change \"<name>\" --json"), precise JSON field names ("artifactPaths.specs.existingOutputPaths", "planningHome.root"), concrete file paths, specific error-message prefixes ("Declared in", "Invalid store declaration in"), and a copy-paste output template. No pseudocode or vague direction.	5 / 5
Workflow Clarity	Six clearly sequenced steps with explicit validation ("openspec validate --specs"), stop-before-write checkpoints on invalid JSON, project-root preflight checks, error-recovery branches per failure mode, and a Guardrails checklist — well above the destructive/batch-operation cap of 3 since validation and feedback loops are present.	5 / 5
Progressive Disclosure	No bundle files exist, so navigation depth is not an issue, but the skill is a ~280-line monolith: reference-like material (the store-selection preamble, Delta/Main Spec Format References, and the six-condition retirement rules) is inlined rather than split into reference files. Structure exists via headers and bold sections, but organization into separate files would serve progressive disclosure better.	3 / 5
	Total	16 / 20 Passed

Description

82%Weight 40%Scale 1-5

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

A strong description: explicit what-and-when structure with concrete command-style trigger phrases and clear differentiation from the archive workflow. The only limitation is that it names a single action rather than enumerating several concrete capabilities.

Suggestions

Enumerate the concrete operations performed during a sync (merge ADDED/MODIFIED requirements, remove retired ones, validate specs) to lift specificity above a single stated action.

Add a couple of natural phrasing variants such as "sync specs" or "apply a delta spec" to broaden trigger-term coverage.

Dimension	Reasoning	Score
Specificity	"Sync delta specs from a OpenSpec change to main specs" names the domain and one concrete action (sync, "without archiving the change"). Only a single action is listed, matching the 1-2-concrete-actions anchor; it is not a 4 since there are not several specific actions.	3 / 5
Completeness	It clearly answers what it does ("Sync delta specs from a OpenSpec change to main specs") and when to use it with explicit concrete triggers ("Use when the user wants to update main specs...", "Also use when the user says 'openspec sync' or 'opsx sync'"), matching the top anchor exactly.	5 / 5
Trigger Term Quality	"openspec sync", "opsx sync", "update main specs", and "delta spec" give good natural keyword coverage including exact command phrasings, but common synonyms like "sync specs" or "merge specs" are missing, so it falls short of the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	It occupies a clear niche (OpenSpec spec syncing) with distinct command-level triggers and explicitly differentiates the adjacent archive operation ("without archiving the change"), minimizing conflict risk.	5 / 5
	Total	17 / 20 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: 2500d6d

Reviewed: 1 day 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.