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.

Quality

74%

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 ./bcs-runtime/bcs-k8s/bcs-component/bcs-drplan-controller/.claude/skills/openspec-sync-specs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

68%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 strongly actionable, well-structured instruction skill with exact commands, paths, and decision rules for applying delta specs. The principal gap is the absence of validation or verification in a destructive batch workflow — there is no step to confirm merged specs are correct before reporting the summary. Minor redundancy and an inlined format reference keep conciseness and progressive disclosure at 4.

Suggestions

Add an explicit validation step after merging and before the summary, e.g. re-read each updated main spec to confirm requirement names match the delta intent and no unmentioned content was lost or duplicated.

Add an error-recovery loop for failure cases, such as a FROM requirement in a RENAMED block that cannot be found in the main spec — specify whether to ask the user, skip with a warning, or abort.

Consolidate the duplicated intelligent-merging guidance from step 3c and the "Key Principle" section into one place, and consider moving the delta spec format reference into a one-level-deep reference file.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence — no concept explanations, just procedure, paths, and a format reference. It falls short of anchor 5 due to minor redundancy: the intelligent-merging guidance ("don't need to copy existing ones" in step 3c vs. "just include that scenario under MODIFIED - don't copy existing scenarios" in the Key Principle section) is stated twice, and the format reference block is slightly long.

4 / 5

Actionability

Concrete, executable guidance throughout: the exact command `openspec list --json`, exact paths (`openspec/changes/<name>/specs/<capability>/spec.md`, `openspec/specs/<capability>/spec.md`), per-section decision rules, and a worked format example. It stops short of anchor 5 because the core merge operation relies on open-ended judgment ("Use your judgment to merge changes sensibly") and step 1 leaves filtering of changes-with-delta-specs implicit rather than specified.

4 / 5

Workflow Clarity

Steps 1-4 are clearly sequenced with good pre-flight guardrails ("Read both delta and main specs before making changes", "Preserve existing content not mentioned in delta"), but the workflow involves destructive and batch edits (REMOVED requirements, edits across multiple main spec files) with no post-operation validation or verification step. Per the rubric's cap, a destructive/batch workflow without validation cannot score above 3.

3 / 5

Progressive Disclosure

Well-organized single-file structure with clearly labeled sections (Steps, Delta Spec Format Reference, Key Principle, Output On Success, Guardrails) and no external references — appropriate for a self-contained skill. It misses anchor 5 because the ~127-line body exceeds the under-50-line simple-skill exception and content like the 25-line format reference could live in a one-level-deep reference file.

4 / 5

Total

15

/

20

Passed

Description

66%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 focused, honest description with a clear what, an explicit Use-when clause, and a well-differentiated openspec niche. Its main weaknesses are narrow action coverage (a single generic "sync" verb instead of the concrete operations) and limited trigger phrasing variations. Anchor 4 for completeness reflects the explicit but single-pattern when clause.

Suggestions

Enumerate the concrete actions in the description, e.g. "Add, modify, remove, and rename requirements in main specs based on a change's delta specs" instead of the single generic "sync" verb.

Broaden the Use-when clause with natural trigger variations users would actually say, such as "Use when the user wants to apply or merge a change's specs, update main specs, or sync specs without archiving the change."

DimensionReasoningScore

Specificity

"Sync delta specs from a change to main specs" names the domain and one concrete action, restated as "update main specs with changes from a delta spec" — it never lists the several distinct operations (add, modify, remove, rename requirements) the skill actually performs. Anchor 3 (domain plus 1-2 actions, not comprehensive) is the closest match; it falls short of 4 because no list of specific actions is given.

3 / 5

Completeness

It has a clear what ("Sync delta specs from a change to main specs") and an explicit when ("Use when the user wants to update main specs with changes from a delta spec, without archiving the change"), including a useful disambiguation from archiving. It sits between anchors 4 and 5: the when is explicit and specific, but it offers only a single trigger phrasing without the variations the anchor-5 example shows, so 4 applies.

4 / 5

Trigger Term Quality

Relevant domain keywords are present ("delta spec", "main specs", "update", "change", "archive") but coverage is narrow — common user phrasings like "apply changes to specs", "merge the change", or "spec sync" are missing. This matches anchor 3 (some relevant keywords, missing variations); it is above 2 because multiple concrete domain terms exist rather than one generic keyword.

3 / 5

Distinctiveness Conflict Risk

Openspec-specific terms ("delta spec", "main specs", "without archiving the change") carve out a clear niche with distinct triggers and minimal overlap with other skills. This clearly matches anchor 5 rather than 4, since the terminology would not plausibly activate an unrelated skill.

5 / 5

Total

15

/

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

TencentBlueKing/bk-bcs

Path

bcs-runtime/bcs-k8s/bcs-component/bcs-drplan-controller/.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.