diagnostics-development
Build effective error messages, warnings, and hints for Biome lint rules using the Diagnostic trait and advice system. Learn to craft messages that explain what went wrong, why it matters, and how to fix it—with rich markup, code frames, and actionable guidance.
diagnostics-development helps you create clear, actionable error messages and warnings for Biome lint rules.
AI-generated summary based on this skill's SKILL.md
Install
biomejs/biome/diagnostics-development · repository language: Rust
git clone https://github.com/biomejs/biome
cp -r biome/.claude/skills/diagnostics-development ~/.claude/skills/diagnostics-developmentnpx skillfed install biomejs/biome/diagnostics-developmentFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to create diagnostics in Biome?
diagnostics-development teaches you to build error messages for Biome lint rules using the Diagnostic trait and RuleDiagnostic builder. Start by deriving the Diagnostic trait on your error type, then use RuleDiagnostic to construct messages with advice, code frames, and markup. The skill covers registering diagnostic categories, configuring severity levels, and applying show-don't-tell philosophy so users understand what went wrong, why it matters, and how to fix it.
What are Biome advice types and how do I use code frame diffs?
diagnostics-development explains that Biome advice types let you attach actionable guidance to diagnostics. Code frame diffs show before-and-after code snippets, helping users visualize fixes. The skill teaches markup formatting for emphasis and clarity, multi-advice diagnostics for complex issues, and how to tag diagnostics as fixable. Together, these create high-quality diagnostic output that guides developers toward resolution.
How do I write lint rule error messages that are user-friendly?
diagnostics-development emphasizes building user-friendly messages by explaining the problem clearly, showing why it matters, and providing concrete next steps. Use markup formatting for readability, include code frames to contextualize errors, and apply the show-don't-tell principle—let the code and diffs speak rather than abstract language. The skill covers best practices for actionable error messages that help developers fix issues quickly.
What is the RuleDiagnostic builder pattern in Biome?
diagnostics-development teaches the RuleDiagnostic builder pattern as the primary way to construct diagnostics for lint rules. This pattern lets you chain methods to set messages, advice, code frames, severity, and tags. The builder approach keeps diagnostic creation readable and maintainable, and the skill shows how to register diagnostic categories and configure severity levels to match your rule's intent.
How do I register diagnostic categories and set severity levels?
diagnostics-development covers registering diagnostic categories to organize your lint rules and configuring severity levels—error, warning, or hint—to control how Biome reports issues. Proper categorization and severity configuration ensure your diagnostics integrate smoothly with Biome's configuration system and user expectations, making linting output consistent and predictable.
What markup formatting and derive macros does Biome diagnostics support?
diagnostics-development teaches markup formatting options for emphasis, code highlighting, and clarity in diagnostic messages. The skill covers the Diagnostic derive macro, which streamlines trait implementation, and shows how to combine markup with code frames and advice for polished, professional diagnostic output that users can quickly parse and act upon.
SKILL.md
rendered from the published skill — quoted content, verbatim
Purpose
Use this skill when creating diagnostics - the error messages, warnings, and hints shown to users. Covers the Diagnostic trait, advice types, and best practices for clear, actionable messages.
Prerequisites
- Read
crates/biome_diagnostics/CONTRIBUTING.mdfor concepts - Understand Biome's Technical Principles
- Follow the "show don't tell" philosophy
Diagnostic Principles
- Explain what - State what the error is (diagnostic message)
- Explain why - Explain why it's an error (advice notes)
- Tell how to fix - Provide actionable fixes (code actions, diff advice, command advice)
Follow Technical Principles: - Informative: Explain, don't just state - Concise: Short messages, rich context via advices - Actionable:
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.claude/skills/diagnostics-development/SKILL.md