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

73%

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 ./.claude/skills/openspec-sync-specs/SKILL.md

Quality

Content

76%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.

A well-structured, highly actionable procedure for an agent-driven spec sync, with concrete paths, decision rules, and an output template. Its main gap is the absence of an explicit validation checkpoint after applying changes, which matters because the operation batch-edits main spec files.

Suggestions

Add a validation step after applying changes, e.g. re-read each modified main spec to confirm requirement counts and section integrity, or run a verification command if the openspec CLI provides one.

Include a fix-and-retry loop for mismatches (e.g., a FROM requirement in a RENAMED entry that cannot be found in the main spec) instead of only the generic "ask for clarification" guardrail.

Trim duplication between the Delta Spec Format Reference block, the step 2 section list, and the Intelligent Merging section to save tokens.

Dimension	Reasoning	Score
Conciseness	The body is lean and procedural, assuming Claude's competence (e.g., "Apply changes intelligently", guardrail bullets). Minor over-explanation: the 25-line Delta Spec Format Reference partially duplicates the section list already given in step 2, and the "Key Principle: Intelligent Merging" section restates step 3c guidance — trimmable, matching anchor 4 rather than 5.	4 / 5
Actionability	Fully concrete guidance for an instruction-only skill: exact paths ("openspec/changes/<name>/specs/*/spec.md"), a runnable command ("openspec list --json"), per-section decision rules for ADDED/MODIFIED/REMOVED/RENAMED, a full format example, and a copy-paste output template. This covers the common cases at anchor 5.	5 / 5
Workflow Clarity	The four steps are clearly sequenced with an early stop condition ("If no delta specs found, inform user and stop") and guardrails. However, this is a batch operation that rewrites main spec files, and there is no post-apply validation step (no re-read check, verification command, or fix-and-retry loop), so the missing-validation cap applies — anchor 3, not 4.	3 / 5
Progressive Disclosure	Well-organized sections (Input, Steps, Format Reference, Key Principle, Output, Guardrails) with no nested references and no bundle files; at ~128 lines everything is appropriately inline. Only minor reorganization is conceivable (the format reference could be split out), matching anchor 4 rather than 5.	4 / 5
	Total	16 / 20 Passed

Description

70%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 concise, third-person description that clearly states both what the skill does and when to use it, with a useful distinguishing clause about not archiving. Its main weaknesses are limited enumeration of the concrete operations performed and modest trigger-term variety.

Suggestions

Enumerate the concrete operations in the description, e.g. "Apply added, modified, removed, and renamed requirements from a change's delta specs to the main specs".

Broaden trigger coverage with synonyms users might say, such as "apply changes to specs", "merge delta specs", or "promote specs from a change".

Name the tool context (openspec) in the description to sharpen distinctiveness against generic spec- or document-management skills.

Dimension	Reasoning	Score
Specificity	"Sync delta specs from a change to main specs" names the domain and a concrete action, but does not enumerate the specific operations (added/modified/removed/renamed requirements). It is more concrete than anchor 2's generic action but lacks the several specific actions of anchor 4.	3 / 5
Completeness	It explicitly answers both what ("Sync delta specs from a change to main specs") and when ("Use when the user wants to update main specs with changes from a delta spec, without archiving the change"), in third person. The 'when' clause is explicit but could include more concrete trigger phrasing, matching anchor 4 rather than 5.	4 / 5
Trigger Term Quality	"Use when the user wants to update main specs with changes from a delta spec" provides natural phrases ("update main specs", "changes from a delta spec") a user would plausibly say. Missing synonyms and variations like "apply", "merge", or "promote", so it falls short of anchor 5's comprehensive coverage.	4 / 5
Distinctiveness Conflict Risk	Niche vocabulary ("delta spec", "main specs") and the distinguishing clause "without archiving the change" give it a clear niche with minimal conflict risk against sibling skills. It does not name the underlying tool (openspec), leaving minor overlap risk with related spec-management skills, so anchor 4 rather than 5.	4 / 5
	Total	15 / 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: mckinsey/agents-at-scale-ark
Path: .claude/skills/openspec-sync-specs/SKILL.md
Commit: 65acf95

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.