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

65%

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

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.

The content is well-structured, concise, and actionable with concrete commands, paths, and a format reference. The key weakness is workflow clarity for a spec-mutating batch operation: it lacks an explicit validation/verification checkpoint before or after editing main specs, which the rubric caps at 3.

Suggestions

Add a validation checkpoint step, e.g. after applying changes run `openspec validate <capability>` (or re-read the main spec) to confirm structure before declaring success.

Include a feedback loop (verify -> fix -> re-verify) for the merge, since editing main specs is a batch/irreversible-ish operation.

Add an example of one merged requirement edit (before/after of a main spec snippet) to make the 'intelligent merging' guidance fully executable.

Dimension	Reasoning	Score
Conciseness	The body is efficient and mostly assumes Claude's competence, with a compact format reference and output template; minor repetition (the sync principle restated as 'Intelligent Merging') could be trimmed, keeping it just below a 5.	4 / 5
Actionability	It gives concrete, executable guidance: exact CLI command (`openspec list --json`), file paths, named tool (AskUserQuestion), and a worked delta format example, with only minor gaps such as no example of an actual merged edit.	4 / 5
Workflow Clarity	Although the four-step sequence is clear, this is a batch operation that mutates main specs (destructive/irreversible-ish edits) yet has no validation or verify-the-result checkpoint — the rubric caps such skills at 3, and the only 'guardrail' about idempotency is stated but not verifiable as a step.	3 / 5
Progressive Disclosure	The SKILL.md is a self-contained overview of appropriate length with well-organized sections (Steps, Format Reference, Key Principle, Output, Guardrails) and no bundle files or nested references, which fits the under-50-line simple-skill exception for a clean 5.	5 / 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 third person, concise, and answers both 'what' and 'when' with a specific trigger clause. Its main weakness is specificity and trigger coverage — it stays at a high level and does not enumerate the concrete requirement operations the skill performs.

Suggestions

Enumerate the concrete operations in the description, e.g. 'add, modify, remove, or rename requirements in main specs based on a delta spec'.

Add natural trigger synonyms such as 'apply a change to specs' or 'promote delta specs' to broaden keyword coverage.

Optionally contrast with archiving (e.g. 'Use this instead of archiving when you only want to update main specs') to sharpen distinctiveness.

Dimension	Reasoning	Score
Specificity	It names the domain (syncing delta specs to main specs) and one concrete action (updating main specs with changes from a delta), but does not enumerate the concrete change types (added/modified/removed/renamed) covered in the body, so coverage is not comprehensive.	3 / 5
Completeness	It clearly states what it does ('Sync delta specs from a change to main specs') and gives an explicit 'when' trigger ('Use when the user wants to update main specs with changes from a delta spec, without archiving the change'), with the 'when' clause specific.	4 / 5
Trigger Term Quality	It uses 'delta spec', 'main specs', and 'change' which are domain terms a user familiar with openspec would say, but it omits natural synonyms or variations and relies on the tool's jargon rather than broad trigger phrases.	3 / 5
Distinctiveness Conflict Risk	The openspec delta-to-main sync niche is fairly distinct from other skills, with only minor overlap risk against generic spec-editing or archive skills.	4 / 5
	Total	14 / 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: PBH-BTN/PeerBanHelper
Path: .claude/skills/openspec-sync-specs/SKILL.md
Commit: f8e9b1b

Reviewed: 3 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.