---
name: biome-lint-format-toolchain
description: "Migrate ESLint+Prettier to Biome 2.x — type-aware lint, biome.json config, GritQL plugins, CI and format-on-save. Production Biome 2.x: run `biome migrate eslint --write` and `biome migrate prettier`, port configs into biome.json with overrides and globs, enable type-aware rules (noFloatingPromises, useExhaustiveDependencies) via the project domain without tsc, author GritQL plugins for custom lint rules, and wire `biome ci` plus the VS Code editor.defaultFormatter for format-on-save and organize-imports assists."
license: MIT
---

# Biome Toolchain Pro

This skill walks a JavaScript/TypeScript project off ESLint and Prettier and onto Biome 2.x as a single lint-and-format toolchain. It's aimed at teams who are tired of reconciling two config files, plugin version drift, and slow CI, and who want type-aware linting without standing up a separate type-check pass. The agent handles the migration mechanics, ports your existing rules, and wires up CI and editor integration.

## When to use it
- You have an `.eslintrc*` and `.prettierrc*` and want one tool with one config.
- You want type-aware rules like `noFloatingPromises` or `useExhaustiveDependencies` but don't want to run `tsc` in lint.
- A monorepo where different packages need different rules via globs/overrides.
- You need a custom lint rule and don't want to write a full ESLint plugin.

## What it does
- Runs `biome migrate eslint --write` and `biome migrate prettier --write` to translate existing configs into `biome.json`, including reading `.eslintrc` extends and inferring `.prettierrc` formatting options.
- Structures `biome.json` with `linter`, `formatter`, `assist`, `files.includes`, and per-path `overrides`.
- Enables the `project` domain so multi-file, type-aware rules work using Biome's own module graph (no TypeScript compiler invocation).
- Authors GritQL plugins (`.grit` files referenced under `plugins`) for project-specific patterns ESLint would have needed a custom rule for.
- Sets up CI via `biome ci` and editor format-on-save through the Biome LSP / `editor.defaultFormatter`.

## Usage

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/biome-lint-format-toolchain/SKILL.md https://claudeskil.com/skills/biome-lint-format-toolchain/SKILL.md

# then, in your repo:
npm i -D --save-exact @biomejs/biome
npx biome migrate eslint --write
npx biome migrate prettier --write
npx biome check --write .   # lint + format + organize imports
npx biome ci .              # what CI runs (no writes)
```

A trimmed `biome.json`:

```json
{
  "linter": {
    "domains": { "project": "recommended" },
    "rules": { "nursery": { "noFloatingPromises": "error" } }
  },
  "plugins": ["./grit/no-console-in-prod.grit"],
  "overrides": [
    { "includes": ["**/*.test.ts"], "linter": { "rules": { "suspicious": "off" } } }
  ]
}
```

## Tips & gotchas
- Pin Biome with `--save-exact`; rule sets shift between minor versions and unpinned upgrades can fail CI unexpectedly.
- Type-aware rules live behind the `project` domain and some are still in `nursery` — enable them explicitly; `recommended` alone won't turn them on.
- `biome migrate` covers rules with a Biome equivalent; unmapped ESLint rules are skipped silently, so diff the before/after rule coverage.
- Biome's type inference is intentionally not a full type-checker — keep `tsc --noEmit` in CI for actual type errors.

## FAQ
**Does Biome replace `tsc`?** No. It catches a curated set of type-aware lint issues without `tsc`, but it does not report type errors. Run both.

**Will it handle my monorepo?** Yes — use a root `biome.json` with `overrides` keyed by `includes` globs, or nested configs with `extends`.

**Can I keep some ESLint rules?** You can run both during transition, but disable overlapping formatting in ESLint to avoid fighting Biome's formatter.