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.

Quality

86%

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

Quality

Content

86%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 tight, actionable skill body: concrete commands and examples, a decision table, and a validation checklist, with policy detail properly delegated to external references. The only weaknesses are a duplicated command statement and an implicitly — rather than explicitly — sequenced workflow without a failure-recovery loop.

Suggestions

Drop the redundant 'Run `just new-changeset-empty` to generate an empty file.' sentence and keep only the shell block, or vice versa.

Number the workflow sections (or add a short 'Workflow' sequence) and state what to do when a Review Checklist item fails, e.g., re-classify the release level and regenerate the entry.

Dimension	Reasoning	Score
Conciseness	The body is lean — a level table, tight bullets, and one markdown example — with no explanations of concepts Claude already knows; only minor trimmable instances remain, e.g., the command 'just new-changeset-empty' appears both as a sentence and immediately again in a shell block, and the nursery exception is partly explained ('because they do not follow semantic versioning').	4 / 5
Actionability	Fully executable guidance throughout: the exact generator command 'just new-changeset-empty', a complete changeset example with the real package name ('"@biomejs/biome": patch'), a concrete change-to-level-to-branch table, and specific heading rules ('Use `####` or `#####` for headings inside a longer entry').	5 / 5
Workflow Clarity	The sections form a clear sequence (decide → choose level → create → write) with a 7-item 'Review Checklist' and an explicit pre-PR checkpoint ('Before opening a PR, explicitly confirm the user-facing classification'), but the ordering is implied by headings rather than explicit steps and there is no error-recovery loop if a checklist item fails.	4 / 5
Progressive Disclosure	The body stays an overview and delegates policy detail to clearly signaled, one-level-deep references in a dedicated References section ('CONTRIBUTING.md#changelog', the versioning URL, 'justfile') rather than inlining them, and no bundle files exist that should be linked.	5 / 5
	Total	18 / 20 Passed

Description

87%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, highly specific description with explicit what/when guidance and clear boundaries via a do-not-use clause. The only deductions are a second-person phrase ('you must decide') that triggers the voice penalty and a few missing natural synonyms.

Suggestions

Rewrite in third person (e.g., 'Use when a Biome change may affect users and a changeset decision, release level, or `.changeset/*.md` entry is required') to avoid the second-person specificity penalty.

Add one or two natural synonyms such as 'release notes' phrasing variants or 'version bump' to broaden trigger term coverage.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — 'decide whether it needs a changeset', 'choose the release level', 'create and edit `.changeset/*.md` release-note text' — which matches the comprehensive anchor (5), but the second-person phrase 'you must decide' triggers the rubric's one-point voice penalty, reducing it to 4.	4 / 5
Completeness	It explicitly answers both what ('decide whether it needs a changeset, choose the release level, or create and edit `.changeset/*.md` release-note text') and when ('Use this skill when a Biome change may affect users'), plus an explicit negative trigger ('Do not use for implementation details or PR descriptions').	5 / 5
Trigger Term Quality	Good natural keyword coverage ('changeset', 'release level', 'release-note', 'Biome change', '`.changeset/*.md`') but a few natural synonyms users might say are missing (e.g., 'version bump', 'changelog'), so it fits the 'good coverage, a few natural terms missing' anchor.	4 / 5
Distinctiveness Conflict Risk	A clear niche — Biome changesets — with distinct trigger phrases and an explicit exclusion clause, giving minimal overlap risk with other skills.	5 / 5
	Total	18 / 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: biomejs/biome
Path: .claude/skills/changeset/SKILL.md
Commit: 40dd3fb

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