CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

changeset

Use this skill when a Biome change may affect users and you must decide whether it needs a changeset, choose the release level, or create and edit `.changeset/*.md` release-note text. Do not use for implementation details or PR descriptions.

76

Quality

95%

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

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 well-crafted, lean instruction skill: a clear sequenced workflow with a validation checklist, concrete commands and templates, and appropriate deferral of canonical policy to repo documents. The main improvement opportunity is a worked example of a completed changeset entry so the prose rules are demonstrable rather than only stated.

Suggestions

Add one short worked example of a finished changeset (frontmatter plus 1-2 sentences following the tense/linking rules) so the Write the Entry rules are shown, not just stated.

Give a one-line rule for picking the package (e.g., which published crates map to which change kinds) instead of delegating package selection wholly to CONTRIBUTING.md.

Trim the redundant fenced `just new-changeset-empty` block since the command is already given inline.

DimensionReasoningScore

Conciseness

The body is lean and assumes competence throughout: a decision table instead of prose, terse writing rules, and non-obvious domain gotchas (nursery rules bypass semver, heading levels that break changelog generation) with zero padding or explanations of concepts Claude already knows. It is not a 4 because the only trim candidate — the `just new-changeset-empty` command shown inline and again in a fenced block — is a single trivial line rather than a real instance of over-explanation.

5 / 5

Actionability

Guidance is mostly executable: the exact command `just new-changeset-empty`, a copy-paste-ready frontmatter template, exact heading levels, and a level/branch table with named anchors. It falls short of 5 due to minor gaps: there is no worked example of a finished entry's prose, and package selection is delegated entirely to `CONTRIBUTING.md` rather than being actionable from the body.

4 / 5

Workflow Clarity

The sections form an explicit sequence (Decide → Choose Release Level → Create the File → Write the Entry) ending in a seven-item Review Checklist that validates the known failure modes ('The file has one valid frontmatter block', 'The release level agrees with branch policy'). Creating a single markdown file is neither destructive nor batch, so the workflow-clarity cap does not apply; it is not a 4 because the checklist is an explicit validation checkpoint rather than an implicit one.

5 / 5

Progressive Disclosure

The body is a compact overview with clearly labeled, one-level-deep references to canonical sources (`CONTRIBUTING.md#changelog`, the versioning page, `justfile`) and no bundle files to bury; nothing that belongs in a separate file is inlined. It is not a 4 because navigation is unambiguous and the split between inline decision guidance and deferred canonical policy is exactly appropriate for this size of skill.

5 / 5

Total

19

/

20

Passed

Description

95%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 excellent description: concrete, comprehensive, explicitly scoped to Biome changesets, with both what and when answered and explicit negative triggers. Its only flaw is the second-person phrasing ('you must decide'), which the rubric penalizes on specificity.

Suggestions

Rewrite in third person to avoid the second-person penalty, e.g., 'Decides whether a Biome change needs a changeset, chooses the release level, and creates/edits `.changeset/*.md` release-note text. Use when a change may affect users of the Biome CLI, libraries, or tooling.'

Consider adding the synonym 'changelog entry' to catch users who phrase the task in terms of the generated changelog rather than the changeset file.

DimensionReasoningScore

Specificity

The description names three concrete actions ('decide whether it needs a changeset, choose the release level, or create and edit `.changeset/*.md` release-note text') with comprehensive domain coverage, matching the score-5 anchor, but it is written in second person ('Use this skill when... you must decide'), which the rubric penalizes by reducing specificity by 1. It is not a 3 because the actions are concrete and complete rather than limited to 1-2.

4 / 5

Completeness

It explicitly answers both what (decide need, choose release level, create/edit `.changeset/*.md` release-note text) and when ('Use this skill when a Biome change may affect users'), with concrete trigger phrases and an explicit exclusion ('Do not use for implementation details or PR descriptions'). A 4 would require the 'when' clause to be less explicit than it is here.

5 / 5

Trigger Term Quality

It covers the natural terms a contributor would say — 'changeset', 'release level', 'release-note text' — plus the file extension `.changeset/*.md`, matching the comprehensive-coverage anchor. It is not a 4 because synonyms ('release-note') and file extensions are both present, not a few terms short.

5 / 5

Distinctiveness Conflict Risk

It is tightly scoped to Biome changesets with clear niche triggers ('Biome change', 'changeset', 'release level') and an explicit do-not-use boundary, giving minimal conflict risk with other skills. It is not a 4 because the exclusions and domain scoping leave no meaningful overlap with 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

biomejs/biome

Path

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