biome: Skill for Claude Code

Formatter Development

Use crates/biome_formatter/CONTRIBUTING.md and the language formatter's guide as the canonical architecture references. Inspect neighboring node implementations before selecting IR primitives.

Workflow

1. Reproduce the behavior with a focused internal formatter spec or quick_test.
2. Inspect the node fields, comments, and nearby formatting rules.
3. Implement the smallest layout change using formatter IR.
4. Run focused formatter tests and inspect snapshots.
5. Compare with Prettier when compatibility is relevant.
6. Format and lint before committing.

Printing Discipline

Formatter output is a structured rewrite of the source tree, not a fresh pretty-printer. Treat every missed node, missed token, unchecked suppression, and untracked replacement as a formatter bug, not as style feedback.

• Every source token in the formatted range MUST be consumed exactly once. A token is consumed only by formatting it, removing it with format_removed, replacing it with format_replaced, or by a language-specific helper that does one of those operations.
• Every source node in the formatted range MUST be handled every time. Prefer node.format() or node.format().with_options(...) so the node's own rule formats the node, checks suppressions, and routes comments through the formatter infrastructure.
• A parent formatter MUST NOT inline a child node's fields just to get a convenient layout. Move the layout decision into the child rule or pass options into the child formatter.
• If an architecture-specific formatter bypasses a node's rule, it MUST NOT skip the node silently. It MUST check f.context().comments().is_suppressed(node.syntax()); if the node is suppressed, it MUST write the language's format_suppressed_node(...) helper instead of formatting the node body. Without this check, debug builds fail suppression coverage and user suppressions can be ignored.
• Source tokens MUST be printed through their typed accessors. Use token("...") only for syntax inserted by the formatter when no source token exists.
• Removing a source token from output MUST use format_removed(&token). Do not drop the field, bind it to _, or omit it from write! without consuming it through format_removed; skipped trivia still belongs to that token.
• Replacing a source token's text MUST use format_replaced(&token, &replacement). Do not print the replacement directly and do not use token("...") for replacement text, because the original token still has trivia and must be marked consumed.
• Custom formatting MUST be carried by a small struct implementing Format<Context>. Do not use free functions or stored closure values to carry formatter state or layout invariants. Use format_with only for one-off local glue that is immediately written.