formatter-development

Guide for implementing formatting rules using Biome's IR-based formatter infrastructure. Use when implementing formatting for new syntax nodes, handling comments in formatted output, writing or debugging formatter snapshot tests, diagnosing idempotency failures, or comparing Biome's formatting against Prettier for JavaScript, CSS, JSON, HTML, Markdown, or other languages.

Quality

96%

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

92%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable and concise with strong workflow clarity and validation checkpoints for idempotency and snapshot testing. The main weakness is progressive disclosure: large reference material and full code examples live inline rather than being split into bundle files.

Suggestions

Move the 'IR Primitives Reference' section into a references/ file (e.g. ir-primitives.md) and link to it from the body, keeping only the most common primitives inline.

Extract the complete FormatJsIfStatement and comment-handling examples into an examples bundle file, leaving a concise representative snippet in SKILL.md.

Add a brief references/ index file so the CONTRIBUTING.md pointers and any extracted reference docs are discoverable in one place.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes competence — mostly commands, code, and targeted notes rather than explanation of general concepts; the prose present (idempotency double-run, .snap file semantics) is niche IR/testing knowledge Claude does not already know, so it earns its tokens. It is not a level-2 'mostly efficient but includes some unnecessary explanation' case.	3 / 3
Actionability	Provides fully executable Rust FormatNodeRule implementations, concrete IR primitive usage, and copy-paste-ready commands ('just gen-formatter html', 'cargo test', 'cargo insta review', prettier-compare invocations); guidance is concrete and complete rather than pseudocode or vague direction.	3 / 3
Workflow Clarity	Multi-step workflows (generate → implement → test → compare) are clearly sequenced with explicit validation checkpoints — 'Run cargo t twice', 'Skipping the second run hides idempotency bugs', 'Always use --rebuild', 'Always create new test cases' — providing the feedback loops the rubric rewards for fragile formatting operations.	3 / 3
Progressive Disclosure	No bundle files exist and the References section uses clean one-level pointers to repo paths, but the full IR Primitives Reference and complete code implementations are inlined in SKILL.md rather than split into separate files; this matches the anchor where content that should be separate is inline.	2 / 3
	Total	11 / 12 Passed

Description

100%Weight 40%Scale 1-3

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 specific, complete, and distinctive: it names concrete formatting actions, gives explicit 'Use when' triggers with natural terms, and is clearly scoped to Biome's formatter. Third-person voice is used throughout with no fluff or over-claims.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'implementing formatting for new syntax nodes', 'handling comments in formatted output', 'writing or debugging formatter snapshot tests', 'diagnosing idempotency failures', 'comparing ... against Prettier' — matching the anchor for multiple specific concrete actions; not merely naming a domain and some actions.	3 / 3
Completeness	Explicitly states both what ('Guide for implementing formatting rules using Biome's IR-based formatter infrastructure') and when ('Use when implementing formatting ... or comparing ...'), satisfying the anchor for clearly answering both what and when with explicit triggers.	3 / 3
Trigger Term Quality	Natural terms a Biome contributor would say are well covered — 'snapshot tests', 'idempotency failures', 'comparing against Prettier', plus language names (JavaScript, CSS, JSON, HTML, Markdown); far beyond jargon or generic phrasing.	3 / 3
Distinctiveness Conflict Risk	Occupies a clear niche — Biome's IR-based formatter infrastructure — with distinct triggers that are unlikely to fire for unrelated skills; third-person voice and no generic overlap language.	3 / 3
	Total	12 / 12 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/formatter-development/SKILL.md
Commit: c50a853

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