Agent Skills: TypeScript Linting & Formatting

It covers the 2026 arbitrage between the two — new projects default to Biome for a fast zero-config start, established/typed-heavy codebases lean ESLint + typescript-eslint — plus a note on Oxlint as a challenger, and the rule to never run Biome and Prettier on the same files.

Out of scope: type checking itself (tsc --noEmit, tsconfig flags) belongs to ts-config; test-runner configuration belongs to ts-testing. </objective>

TypeScript Linting & Formatting

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Detect existing lint/format config, project age, framework
2. fuse-ai-pilot:research-expert - Verify latest Biome 2.x + typescript-eslint via Context7/Exa
3. mcp__context7__query-docs - Check Biome and typescript-eslint docs

After implementation, run fuse-ai-pilot:sniper for validation.

Use when

• Choosing a linter/formatter stack for a TS project (new vs established codebase)
• Configuring Biome 2.x (biome.json, biome check, domains, type-aware rules)
• Configuring ESLint 10 flat config + typescript-eslint typed linting
• Migrating from ESLint+Prettier, or adding a CI lint gate

Do NOT use for

• Runtime execution → use ts-runtime-node / ts-runtime-bun
• Framework-specific style rules owned by that framework's own config
• Type checking itself — linters complement, never replace, tsc --noEmit

Critical Rules

1. Pick ONE formatter - Biome formats AND lints in one binary; do not also run Prettier on the same files.
2. Type-aware linting needs the type checker - typescript-eslint typed rules and Biome's type-aware rules both cost a build pass; expect them to be slower than syntactic rules.
3. Biome does NOT format-lint - It never reports formatting via lint rules; the formatter owns all formatting decisions.
4. ESLint 10 = flat config only - Use eslint.config.mjs with typescript-eslint's tseslint.configs.*; .eslintrc.* / .eslintignore support was removed in v10 (ESLint 9 is EOL since 2026-08-06). typescript-eslint 8.x peers on typescript <6.1.0 — on a TS 7.0 project, alias typescript to @typescript/typescript6 for the linter (see eslint-typed.md).
5. Coverage gap is real - Biome's type-aware rules cover ~75% of typed-linting needs; full cross-file narrowing and no-unsafe-* still require typescript-eslint.

Architecture

project/
├── biome.json            # Biome path: one binary, format + lint
│   OR
├── eslint.config.mjs     # ESLint path: flat config + typescript-eslint
├── .prettierrc           #   (only on ESLint path; Biome replaces Prettier)
└── tsconfig.json         # required for typed linting (both tools)

→ See config-examples.md for both stacks

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | Tool choice (2026) | tool-choice.md | Deciding Biome vs ESLint; Oxlint challenger | | Biome setup | biome-setup.md | Configuring biome.json, rules, domains, CI | | ESLint typed | eslint-typed.md | Flat config + typescript-eslint typed linting |

Templates

| Template | When to Use | |----------|-------------| | config-examples.md | Copy a Biome or ESLint config into a project |

Best Practices

DO

• New project → default to Biome 2.x (one binary, fast, zero-config start)
• Established/typed-heavy codebase → ESLint 10 + typescript-eslint typed linting
• Run the linter in CI with error severity to gate merges

DON'T

• Run Biome and Prettier on the same files (conflicting formatting)
• Enable typed linting and then complain about speed — it's the type checker cost
• Assume Biome covers every typescript-eslint rule — check the gaps first