CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

77

Quality

96%

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

92%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 strong operational skill: a resumable state machine with concrete gh/git/pnpm commands, explicit validation gates and failure-recovery loops, and clean one-level-deep disclosure of the release-notes reference. The only weakness is minor guardrule repetition across sections that could be consolidated.

Suggestions

Consolidate the repeated 'never push an empty commit to retrigger CI' rule into one location (e.g., Handle failures) and reference it from the other sections instead of restating it three times.

State the temporary-worktree rule once in Principles and drop the restated justifications in the changeset-PR and Version Packages validation steps, keeping only the step-specific details (e.g., detached worktrees for base/head validation).

DimensionReasoningScore

Conciseness

The body is dense with non-obvious operational guardrails and executable commands, assuming Claude's competence (no explanation of what Changesets or merge queues are). However, a few rules are restated across sections — "never push an empty commit" appears in Principles, the changeset-PR section, and Handle failures, and the temporary-worktree rule appears in both Principles and step guidance — so it sits at "efficient; minor instances that could be trimmed" rather than every token earning its place. Not 3: there is no concept-explanation padding or filler anywhere; the only slack is deliberate guardrail repetition.

4 / 5

Actionability

Nearly every step carries a copy-paste-ready command with exact flags and JSON fields — `gh release list ... --exclude-drafts --exclude-pre-releases --jq 'max_by(.publishedAt)...'`, `gh pr list --head changeset-release/main --json ...`, `git log --first-parent ... <stable-tag>..origin/main`, `pnpm exec changeset status --output changeset-status.json`, `npm view @fission-ai/openspec@<version> version`. The few un-commanded steps (beta workflow trigger, detached worktrees) still name the exact workflow file, refs, and fields (`baseRefOid`, `mergeQueueEntry`), covering the common cases fully. Not 4: the gaps are confined to an uncommon path and the named identifiers leave nothing ambiguous.

5 / 5

Workflow Clarity

The skill is framed as a resumable state machine with a nine-state audit classification, explicit validation checkpoints at every stage ("Validate before pushing", base-to-head worktree comparison, "Verify all three artifacts independently"), a dedicated failure-recovery section with feedback loops (stale PR, queued PR, existing npm version), and a completion checklist. Not 4: validation is not merely present but triple-artifact-independent and gate-ordered (merge-queue entry ≠ merge; only `mergedAt` on `main` advances state).

5 / 5

Progressive Disclosure

The body is a well-sectioned overview/state machine, and the only bundle file — references/release-notes.md (verified to exist) — is linked exactly once ("read [references/release-notes.md](references/release-notes.md)"), at the precise point it is needed, and is itself one level deep with no further nesting. The detailed notes-formatting material is appropriately split out of the main workflow. Not 4: there are no buried references or inlined content that clearly belongs in a separate file.

5 / 5

Total

19

/

20

Passed

Description

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

An exemplary description: comprehensive concrete actions, two explicit trigger clauses covering action requests and status/resumption questions, and a tightly-scoped niche with minimal conflict risk. Third-person-appropriate imperative trigger form matches the reference good examples.

DimensionReasoningScore

Specificity

The description enumerates six concrete actions spanning the full lifecycle — "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" — which is comprehensive, multi-action coverage matching the anchor-5 example. Not 4: there are no minor coverage gaps; every phase of the release workflow is explicitly named.

5 / 5

Completeness

Both questions are answered explicitly with concrete trigger phrases: the "what" is the six-action capability list, and the "when" appears twice ("Use this skill when releasing OpenSpec" and "Also use when asked whether an open release PR is complete..."). This mirrors the anchor-5 example structure. Not 4: the "when" clause is not merely present but enumerates specific user intents rather than a single generic condition.

5 / 5

Trigger Term Quality

Natural user phrasings are covered directly: "releasing OpenSpec", "cut a beta or stable release", "verify publishing", "polish GitHub release notes", plus a second explicit trigger clause for status questions — "whether an open release PR is complete", "what the next release step is", "continue a release paused for human approval". These are the exact questions a user would ask; nothing common is missing for this domain.

5 / 5

Distinctiveness Conflict Risk

The niche is unambiguous — repository-scoped to OpenSpec with tool-specific vocabulary (Changesets, "Version Packages PR", catch-up changeset, beta dist-tag) — so it would not trigger for generic versioning, changelog, or other repos' release skills. Not 4: no meaningful overlap remains; even a generic "make a release" skill would lose the tie on the named repository and Changesets artifacts.

5 / 5

Total

20

/

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