CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

60

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/openspec-sync-specs/SKILL.md
SKILL.md
Quality
Evals
Security

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.

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.

DimensionReasoningScore

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

Description

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

The description is clear, in third person, and answers both what the skill does and when to use it, with domain-specific terminology that limits conflict risk. Its weaknesses are a single-action view of the capability and a when-clause that paraphrases the what instead of supplying distinct natural-language triggers, leaving moderate keyword coverage.

Suggestions

List the concrete operations in the description, e.g. 'Sync delta specs (ADDED, MODIFIED, REMOVED, RENAMED requirements) from a change into main specs' to lift specificity.

Add natural trigger phrases users would actually say, such as 'Use when the user asks to apply delta specs, update main specs from a change, or sync specs without archiving.'

Include a synonym or two for 'sync' (e.g. 'apply' or 'merge') so the description matches how users phrase the request.

DimensionReasoningScore

Specificity

The description names its domain and one concrete action — 'Sync delta specs from a change to main specs' — but stops there, offering no coverage of the underlying operations (adding, modifying, removing, renaming requirements). It matches the anchor for naming a domain with 1-2 concrete actions without being comprehensive; it falls short of anchor 4, which expects several specific listed actions.

3 / 5

Completeness

Both parts are explicit: the 'what' is 'Sync delta specs from a change to main specs' and the 'when' is 'Use when the user wants to update main specs with changes from a delta spec, without archiving the change.' It is not a 5 because the when-clause largely restates the what instead of adding distinct concrete trigger phrases; it is above a 3 because the 'Use when' guidance is explicitly stated, not merely implied.

4 / 5

Trigger Term Quality

Relevant terms are present ('sync', 'delta spec', 'main specs', 'update main specs'), but common variations a user might naturally say — 'apply changes', 'apply the delta', 'merge specs into main' — are absent. This sits at 'some relevant keywords but missing common variations or synonyms' rather than the good coverage of anchor 4.

3 / 5

Distinctiveness Conflict Risk

The openspec-specific vocabulary ('delta specs', 'main specs', 'change') carves out a clear niche, and 'without archiving the change' explicitly separates it from the sibling archive workflow. Minor overlap risk remains with other openspec skills that also touch specs, so it is mostly distinct rather than the minimal-conflict profile of anchor 5.

4 / 5

Total

14

/

20

Passed

Validation

100%

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

dwmkerr/livedown

Path

.claude/skills/openspec-sync-specs/SKILL.md

Reviewed

Table of Contents

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.