Biome Complete Toolchain

When to Apply

Use this skill when the request includes:

• "set up Biome"
• "configure biome.json"
• "migrate from ESLint" or "migrate from Prettier"
• "fix lint and format drift"
• "run Biome in CI"

When Not to Apply

Do not use this skill when the user asks for ESLint-only or Prettier-only solutions.

Principles

1. Use one source of truth for linting and formatting.
2. Prefer deterministic commands and verifiable output.
3. Keep SKILL.md short; move deep details to references/.

Deterministic Workflow

1. Confirm scope: migration, config, lint, format, or CI.
2. Initialize config if missing: bunx @biomejs/biome init.
3. Run checks and capture results: bunx @biomejs/biome check ..
   • Verify: Confirm diagnostics are printed. If command fails, check Node.js version (≥14) and file permissions.
4. Apply safe autofixes: bunx @biomejs/biome check . --write.
   • Verify: Re-run biome check . and confirm reduced error count. If errors persist, review unsupported rules or migration conflicts in references/migration-eslint-prettier.md.
5. Add targeted suppressions only when justified.
6. Verify commands pass in local and CI contexts: bunx @biomejs/biome check . --error-on-warnings.
   • Verify: Exit code 0 indicates success. If non-zero, review remaining diagnostics and address or document exceptions.

Error Recovery: If biome check fails after migration, isolate conflicting rules by temporarily disabling rule groups in biome.json linter section, then re-enable one group at a time to identify the source.

Quick Commands

Initialize

bunx @biomejs/biome init

Expected result: biome.json exists.

Check repository

bunx @biomejs/biome check .

Expected result: diagnostics printed with file paths.

Apply safe fixes

bunx @biomejs/biome check . --write

Expected result: fixable issues are rewritten.

Format files

bunx @biomejs/biome format . --write

Expected result: formatting is normalized.

Check one file

bunx @biomejs/biome check src/index.ts

Expected result: file-level diagnostics only.

Run in CI

bunx @biomejs/biome check . --error-on-warnings

Expected result: non-zero exit when warnings or errors exist.

Anti-Patterns

NEVER run Biome and ESLint on the same files

WHY: Competing rules create contradictory output and noisy reviews.

BAD: ESLint and Biome both lint src/**/*.ts. GOOD: Route TS linting and formatting through Biome only.

Consequence: Duplicate diagnostics and unstable CI outcomes.

NEVER run Prettier and Biome formatter on the same files

WHY: Different formatting models cause churn in every commit.

BAD: prettier --write . and biome format . --write in the same pipeline. GOOD: Keep only biome format . --write for supported files.

Consequence: Constant formatting diffs and merge friction.

NEVER skip biome.json customization after init

WHY: Defaults may not match repository conventions.

BAD: Commit default config without reviewing formatter/linter settings. GOOD: Define formatter width, linter domains, and VCS ignores explicitly.

Consequence: Inconsistent style and avoidable lint regressions.

NEVER blanket-ignore diagnostics to get green CI

WHY: Broad suppressions hide real defects and debt.

BAD: Disable full rule groups without rationale. GOOD: Add narrow suppressions with a reason and follow-up ticket.

Consequence: Quality silently degrades over time.

References

• Config: biome.json — full biome.json schema, formatter width, linter domains, and VCS ignore patterns
• Linting Rule Categories — all rule groups, severity levels, and category-level enable/disable patterns
• Formatter Options — indent style, line width, quote style, and language-specific overrides
• Migration: ESLint & Prettier — step-by-step migration guide, rule mapping, and conflict resolution