CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

release-openspec

Use this skill when releasing OpenSpec: audit merged work and changeset coverage, decide whether a catch-up changeset PR is needed, prepare or resume the Changesets Version Packages PR, cut a beta or stable release, verify publishing, and polish GitHub release notes. Also use when asked whether an open release PR is complete, what the next release step is, or to continue a release paused for human approval.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

88%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 and well-sequenced release runbook with real validation checkpoints and failure recovery, plus one well-integrated reference file. The main improvements are tightening the repeated merge-queue guidance and moving some inlined sub-workflow detail into reference files.

Suggestions

Consolidate the merge-queue guidance (currently restated in Principles, the changeset-PR continuation, and the Version Packages validation sections) into one place and cross-reference it to save tokens.

Move the detailed Version Packages PR validation steps and the beta-cutting path into a reference file (like release-notes.md) so SKILL.md stays a leaner overview of the state machine.

Trim the artifact-verification bullet about the 8 openspec-* archives and SHA256SUMS to the essential rule (wait for SHA256SUMS via the Binaries workflow) and keep exact counts in a reference if needed.

DimensionReasoningScore

Conciseness

The body is dense, imperative, and free of explanations of concepts Claude already knows — it teaches only non-obvious, repo-specific constraints (tag conflicts, merge-queue semantics, Binaries workflow timing). It falls short of a 5 because merge-queue caution is repeated across Principles, the changeset-PR continuation, and the Version Packages validation sections, and a few passages could be tightened further.

4 / 5

Actionability

Guidance is copy-paste ready throughout: exact commands with flags and jq filters ("gh release list ... --exclude-drafts --exclude-pre-releases ... --jq 'max_by(.publishedAt) | {tagName, publishedAt}'", "git log --first-parent ... <stable-tag>..origin/main", "pnpm exec changeset status"), plus concrete verification commands like "npm view @fission-ai/openspec@<version> version". Specific examples cover the common cases.

5 / 5

Workflow Clarity

The workflow is a clearly sequenced state machine with a nine-state audit classification and explicit validation checkpoints: validate with "pnpm exec changeset status" before pushing, require "baseRefOid" to equal current origin/main, base-to-head worktree comparison, independent verification of all three release artifacts, and a dedicated failure-handling section with recovery guidance and feedback loops.

5 / 5

Progressive Disclosure

The single bundle reference (references/release-notes.md) is real, one level deep, clearly signaled via a markdown link, and context-gated ("Once all artifacts exist, read [references/release-notes.md]..."), and the body is organized under clear section headers. It misses a 5 because the ~170-line body inlines detailed sub-workflows (Version Packages validation, beta path, failure handling) that could be split into references to keep SKILL.md closer to an overview.

4 / 5

Total

18

/

20

Passed

Description

92%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 that explicitly states both what the skill does and when to use it, with concrete repo-specific actions and trigger phrases. The only gap is modest synonym coverage (e.g., publish/changelog phrasings) in the trigger terms.

DimensionReasoningScore

Specificity

The description lists six concrete actions — "audit merged work and changeset coverage", "decide whether a catch-up changeset PR is needed", "prepare or resume the Changesets Version Packages PR", "cut a beta or stable release", "verify publishing", "polish GitHub release notes" — giving comprehensive coverage of the skill's capabilities with no vague filler.

5 / 5

Completeness

Both questions are explicitly answered: the opening "Use this skill when releasing OpenSpec:" pairs an explicit when-clause with the full action list, and "Also use when asked whether an open release PR is complete..." adds concrete additional trigger phrases. This matches the anchor-5 example structure exactly, not anchor 4 where the when-clause is less explicit.

5 / 5

Trigger Term Quality

Natural trigger phrases are present ("releasing OpenSpec", "cut a beta", "what the next release step is", "continue a release paused for human approval") but a few common user phrasings such as "publish", "version bump", or "changelog" are missing. It sits above anchor 3 (missing common variations) but short of anchor 5's synonym-and-extension completeness.

4 / 5

Distinctiveness Conflict Risk

The description is anchored to a clear niche — the OpenSpec release workflow with Changesets-specific vocabulary ("Changesets Version Packages PR", "catch-up changeset PR", "beta") — so it would rarely trigger for the wrong skill. Far beyond anchor 4's "minor overlap risk with closely related skills".

5 / 5

Total

19

/

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

Fission-AI/OpenSpec

Path

.agents/skills/release-openspec/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.