Agent skill
biome-typescript
Configure and use Biome (biomejs) for TypeScript linting and formatting. Use when setting up Biome in a project, configuring lint rules, migrating from ESLint/Prettier, fixing lint errors, setting up CI pipelines with Biome, or configuring git hooks for code quality. Covers biome.json configuration, file inclusion/exclusion patterns, rule overrides, and integration with build tooling.
Install this agent skill to your Project
npx add-skill https://github.com/leynos/agent-helper-scripts/tree/main/skills/biomejs
SKILL.md
Biome TypeScript Linting Skill
Routing Guide
| Task | Section |
|---|---|
| Install or update Biome | Version Discovery |
| Initial setup | Quick Start |
| Configure rules | Configuration Patterns |
| Include/exclude files | File Targeting |
| Fix specific lint errors | See references/lint-solutions.md |
| Stricter rules beyond recommended | See references/strict-rules.md |
| Migrate from ESLint/Prettier | See references/migration.md |
| CI and git hooks | See references/ci-hooks.md |
Version Discovery
Never trust cached knowledge of Biome versions. Query the npm registry:
npm view @biomejs/biome version
Or for all recent versions:
npm view @biomejs/biome versions --json | tail -20
Check release notes for breaking changes:
curl -s https://api.github.com/repos/biomejs/biome/releases/latest | jq -r '.tag_name, .html_url'
Quick Start
Install as dev dependency (always pin exact version):
npm install --save-dev --save-exact @biomejs/biome@latest
npx biome init
This creates biome.json. Immediately verify:
npx biome check .
Minimal biome.json
{
"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true
},
"organizeImports": {
"enabled": true
},
"linter": {
"enabled": true,
"rules": {
"recommended": true
}
},
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2
}
}
Critical: Update the $schema URL to match your installed version.
Configuration Patterns
Rule Severity Levels
{
"linter": {
"rules": {
"recommended": true,
"suspicious": {
"noExplicitAny": "error",
"noArrayIndexKey": "warn"
},
"style": {
"noNonNullAssertion": "off"
}
}
}
}
Levels: "error" | "warn" | "off"
Rules with Options
Some rules accept configuration objects:
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"level": "error",
"options": {
"strictCase": false,
"conventions": [
{
"selector": { "kind": "variable" },
"formats": ["camelCase", "CONSTANT_CASE"]
}
]
}
}
},
"complexity": {
"noExcessiveCognitiveComplexity": {
"level": "error",
"options": {
"maxAllowedComplexity": 15
}
}
}
}
}
}
Extending Configurations
{
"extends": ["./biome.base.json"]
}
Arrays merge; later entries override earlier ones.
File Targeting (Rough Edges)
Global Include/Exclude
Top-level files applies to all tools (linter, formatter, organizeImports):
{
"files": {
"include": ["src/**", "tests/**"],
"ignore": ["**/generated/**", "**/*.d.ts", "**/dist/**"]
}
}
Gotcha: Patterns are relative to biome.json location. Use **/ prefix for recursive matching.
Tool-Specific Include/Exclude
Each tool can have its own file scope:
{
"linter": {
"include": ["src/**"],
"ignore": ["src/generated/**"]
},
"formatter": {
"include": ["src/**", "scripts/**"],
"ignore": ["src/vendor/**"]
}
}
Per-File Rule Overrides
Apply different rules to specific file patterns:
{
"overrides": [
{
"include": ["**/*.test.ts", "**/*.spec.ts"],
"linter": {
"rules": {
"suspicious": {
"noExplicitAny": "off"
}
}
}
},
{
"include": ["scripts/**"],
"linter": {
"rules": {
"suspicious": {
"noConsoleLog": "off"
}
}
}
},
{
"include": ["**/*.config.ts", "**/*.config.js"],
"linter": {
"rules": {
"style": {
"noDefaultExport": "off"
}
}
}
}
]
}
Critical ordering: Overrides apply in array order. Later overrides win for the same file.
VCS Integration
Let Biome respect .gitignore:
{
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true,
"defaultBranch": "main"
}
}
With useIgnoreFile: true, anything in .gitignore is automatically excluded.
Command Reference
# Check without modifying (CI mode)
npx biome check .
# Fix all auto-fixable issues
npx biome check --write .
# Lint only (no formatting)
npx biome lint .
# Format only
npx biome format --write .
# Organize imports only
npx biome check --organize-imports-enabled=true --write .
# Check specific files
npx biome check src/index.ts src/utils/**/*.ts
# Output as JSON (for tooling)
npx biome check --reporter=json .
# Show which files would be processed
npx biome check --files-ignore-unknown=true --no-errors-on-unmatched .
Useful Flags
| Flag | Purpose |
|---|---|
--write |
Apply fixes |
--unsafe |
Apply unsafe fixes (review carefully) |
--staged |
Only check git-staged files |
--changed |
Only check files changed since default branch |
--reporter=json |
Machine-readable output |
--diagnostic-level=error |
Exit non-zero only on errors (ignore warnings) |
Suppression Comments
Suppress specific rules inline:
// biome-ignore lint/suspicious/noExplicitAny: external API requires any
const response: any = await legacyApi.fetch();
// biome-ignore lint/style/noNonNullAssertion: checked above
const element = document.getElementById("root")!;
Always include a reason after the colon. Biome enforces this—reasonless suppressions fail.
Avoid these lazy patterns:
// BAD: Will need revisiting
// biome-ignore lint/suspicious/noExplicitAny: TODO fix later
// biome-ignore lint/suspicious/noExplicitAny: too complex to type
// GOOD: Explains why suppression is necessary
// biome-ignore lint/suspicious/noExplicitAny: FFI boundary with untyped C library
// biome-ignore lint/suspicious/noExplicitAny: generic deserializer, caller provides type
Package.json Scripts
{
"scripts": {
"lint": "biome check .",
"lint:fix": "biome check --write .",
"format": "biome format --write .",
"check": "biome check --write --unsafe ."
}
}
TypeScript Integration
Biome does not use tsconfig.json for path resolution by default. For monorepos or path aliases:
{
"javascript": {
"jsxRuntime": "reactClassic",
"globals": ["React"]
}
}
For JSX:
{
"javascript": {
"jsxRuntime": "automatic"
}
}
When to Consult Reference Files
- Struggling with a specific lint error? →
references/lint-solutions.md - Want stricter rules than "recommended"? →
references/strict-rules.md - Migrating from ESLint or Prettier? →
references/migration.md - Setting up CI or git hooks? →
references/ci-hooks.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
logisphere-design-review
Pre-implementation design review framework using the df12 Logisphere crew. Stress-tests system designs, RFCs, ADRs, API proposals, data models, and architecture decisions before code gets written. Each expert examines the design through their specialist lens — structural integrity (Pandalump), alternative approaches (Wafflecat), scaling characteristics (Buzzy Bee), contract design (Telefono), failure modes (Doggylump), and long-term viability (Dinolump). Includes a structured pre-mortem and alternatives checkpoint. Use this skill when asked to review a design document, RFC, ADR, system proposal, API design, or architecture decision — or when asked "should we build it this way", "what could go wrong", "design review", "pre-mortem", "architecture review", "RFC review", or any request for pre-implementation feedback.
implementation-postmortem
Conduct structured implementation postmortems to gather feedback on architecture conformance, library friction, and tooling effectiveness. Use when reviewing completed implementations, PRs, or development phases to surface design gaps, boundary violations, and improvement opportunities. Triggers on requests for code review feedback, implementation retrospectives, architecture audits, or library/tooling evaluations.
code-review
Conduct thorough, actionable code reviews that catch real problems without drowning in noise
execplans
Write and maintain self-contained ExecPlans (execution plans) that a novice can follow end-to-end; use when planning or implementing non-trivial repo changes.
leta
Fast semantic code navigation via LSP. Load FIRST before ANY code task - even 'simple' ones. Trigger scenarios: (1) fixing lint/type/pyright/mypy warnings or errors, (2) fixing reportAny/reportUnknownType/Any type errors, (3) adding type annotations, (4) refactoring or modifying code, (5) finding where a function/class/symbol is defined, (6) finding where a symbol is used/referenced/imported, (7) understanding what a function calls or what calls it, (8) exploring unfamiliar code or understanding architecture, (9) renaming symbols across codebase, (10) finding interface/protocol implementations, (11) ANY task where you'd use ripgrep to find code or read-file to view a function. Use `leta show SYMBOL` instead of read-file, `leta refs SYMBOL` instead of ripgrep for usages, `leta grep PATTERN` instead of ripgrep for definitions, `leta files` instead of list-directory.
logisphere-experts
Community-of-experts review framework using the df12 Logisphere crew for software engineering tasks. Each expert brings a distinct engineering perspective: architecture (Pandalump), creative alternatives (Wafflecat), performance and observability (Buzzy Bee), type safety and contracts (Telefono), reliability and ops (Doggylump), and developer experience (Dinolump). Use this skill when asked to review code, design systems, evaluate architecture decisions, debug complex issues, assess production readiness, or when a thorough multi-perspective engineering analysis is needed. Triggers include: "review this", "what do you think of this design", "is this production-ready", "logisphere review", "expert review", "community review", "crew review", or any request for comprehensive engineering feedback.
Didn't find tool you were looking for?