Ultracite Agent Skill

Ultracite Skill

Fast, zero-config linting and formatting for modern JavaScript/TypeScript projects

Overview

Ultracite is a unified linting and formatting solution that supports multiple providers: Biome (default, Rust-based), ESLint+Prettier+Stylelint, and Oxlint+Oxfmt. It provides framework-specific presets and zero-configuration defaults, replacing traditional ESLint+Prettier setups with a faster, simpler alternative. Ultracite operates invisibly in the background, automatically formatting code and applying fixes on every save.

Version 7 Changes: Multi-provider architecture, preset path migration, MCP server support, AI hooks

Version 6 Changes: Framework-specific presets introduced (React, Next.js, Vue, Svelte, etc.)

Core Goals

• Lightning-Fast Performance: Leverages Biome's Rust implementation for instant linting/formatting
• Zero-Config Design: Ships with 200+ sensible defaults optimized for modern TypeScript development
• Simplicity & Invisibility: Operates with minimal user interaction
• Type Safety: Enforces TypeScript strict mode and comprehensive null/undefined handling
• Tool Compatibility: Works alongside other development tools without conflicts

Key Benefits vs Alternatives

vs ESLint + Prettier:

• 10-100x faster performance (Rust vs JavaScript)
• Single tool instead of two
• Zero configuration needed
• Auto-fixes on save by default
• Built-in TypeScript strict mode

vs Biome alone:

• 200+ preconfigured rules
• Framework-specific presets (React, Next.js, Vue, Svelte)
• AI editor integration (Cursor, Claude Code, Copilot)
• Git hook integrations
• Migration tooling

When to Use This Skill

✅ Ideal Projects

Use Ultracite when:

• Starting a new JavaScript/TypeScript project
• Building with React, Next.js, Vue, Svelte, or other modern frameworks
• Working in monorepos (Turborepo, Nx, Lerna)
• Teams want consistent formatting without bikeshedding
• Performance is critical (large codebases, CI/CD optimization)
• Migrating from ESLint + Prettier to a faster solution
• Using AI coding assistants (Cursor, Claude Code, Windsurf)
• TypeScript projects requiring strict type safety
• Projects with accessibility requirements (ARIA, semantic HTML)

⚠️ Consider Alternatives When

Limited framework support:

• Need Angular/Ember-specific rules (Biome support is basic)
• Require advanced CSS linting (Stylelint still recommended)

Specialized requirements:

• Need specific ESLint plugins not replicated in Biome
• Require property ordering in CSS (Stylelint feature)
• Team has extensive custom ESLint configurations

Legacy projects:

• Large codebases with custom ESLint rules (migration effort required)
• Projects with extensive Prettier customization

For detailed limitations and workarounds, see: references/limitations-and-workarounds.md

Interactive Components

This skill provides interactive commands and autonomous agents for streamlined workflows:

Commands

• /ultracite:doctor - Validate project setup, check for v6→v7 preset paths, detect conflicts
• /ultracite:migrate - Interactive migration wizard (ESLint/Prettier → Ultracite, v6→v7 upgrade)

Agents

• config-validator - Analyze biome.jsonc for syntax, preset paths, rule conflicts, performance
• migration-assistant - Guide ESLint/Prettier migrations with rule mapping and gap analysis

See README.md for complete interactive features documentation.

Choosing a Provider

Ultracite v7 supports three linting providers. Choose based on your needs:

🚀 Biome (Default) - Recommended for most projects

• Speed: Fastest (10-100x faster than ESLint)
• Setup: Zero-config with 200+ preset rules
• Best for: New projects, TypeScript-first development, performance-critical builds
• Limitations: Fewer rules than ESLint, basic CSS/SCSS support

🔧 ESLint + Prettier + Stylelint - Recommended for maximum compatibility

• Speed: Slower but mature ecosystem
• Setup: Requires more configuration
• Best for: Projects with existing ESLint plugins, advanced CSS/SCSS linting needs
• Limitations: JavaScript-based (slower), requires multiple tools

⚡ Oxlint + Oxfmt - Recommended for maximum speed

• Speed: Fastest linting (even faster than Biome for linting only)
• Setup: Type-aware linting with TypeScript integration
• Best for: Large TypeScript codebases, type-safety-critical projects
• Limitations: Newer ecosystem, fewer rules than ESLint

Provider selection during init:

bun x ultracite init --linter biome   # Default
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt

Load provider-specific documentation:

• Biome: references/provider-biome.md
• ESLint: references/provider-eslint.md
• Oxlint: references/provider-oxlint.md

Version Migration Guide

Upgrading from v6 to v7

Breaking Change: Preset paths have changed in v7.

v6 paths (old):

{
  "extends": ["ultracite/core", "ultracite/react"]
}

v7 paths (new):

{
  "extends": ["ultracite/biome/core", "ultracite/biome/react"]
}

Migration steps:

• Update ultracite package: bun update ultracite
• Update preset paths in biome.jsonc (add /biome/ segment)
• Run npx ultracite doctor to validate configuration
• Test linting: npx ultracite check .

New v7 features:

• Multi-provider support (Biome, ESLint, Oxlint)
• MCP server integration for AI assistants
• AI hooks (auto-format after AI edits)
• Type-aware linting (Oxlint)
• ultracite doctor diagnostics command

Load full v7 migration guide: references/v7-migration.md

Upgrading from v5 to v6

Key Change: Framework-specific presets introduced.

v5 approach (old):

{
  "extends": ["ultracite/core"]
}

v6 approach (new):

{
  "extends": ["ultracite/core", "ultracite/react"]  // Framework preset
}

Load full v6 migration guide: references/v6-migration.md

Project Suitability Assessment

When this skill is invoked, scan the project and assess:

• Check existing tooling:

   # Check for ESLint
   ls -la .eslintrc* eslint.config.* package.json | grep eslint

   # Check for Prettier
   ls -la .prettierrc* prettier.config.* package.json | grep prettier

   # Check for Biome
   ls -la biome.json* package.json | grep biome

• Identify framework:
• Check package.json for react, next, vue, svelte, etc.
• Recommend appropriate preset

• Assess project size:
• Large projects (1000+ files) benefit most from Rust performance
• Small projects may not notice speed difference

• Check TypeScript config:
• If tsconfig.json exists, note that Ultracite requires strictNullChecks: true
• Warn if disabled (will generate many warnings)

• Recommend or warn:

   ✅ RECOMMENDED: This TypeScript + React project is ideal for Ultracite
   - 500+ files will benefit from Rust performance
   - React preset available
   - Can replace existing ESLint + Prettier setup

   ⚠️ CONSIDER: This project uses advanced ESLint plugins
   - Custom rule: eslint-plugin-custom-security
   - May need to retain ESLint for these specific rules
   - Could use Ultracite for formatting only

Installation & Setup

Prerequisites

• Node.js v14.18+ (v18+ recommended)
• Package manager: Bun (preferred), npm, pnpm, or yarn
• package.json file in project root

Quick Start (Interactive)

# Using Bun (preferred for speed)
bun x ultracite init

# With provider selection (v7+)
bun x ultracite init --linter biome   # Default, fastest
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt (type-aware)

# Using npm
npx ultracite init

# Using pnpm
pnpm dlx ultracite init

# Using yarn
yarn dlx ultracite init

The interactive setup will:

• Prompt for provider selection (Biome, ESLint, Oxlint) - v7+ only
• Install Ultracite and provider dependencies
• Prompt for framework selection (React, Next.js, Vue, etc.)
• Ask about editor setup (VS Code, Cursor, etc.)
• Offer AI agent rules installation (Cursor, Claude Code, Copilot)
• Prompt for Git hook integration (Husky, Lefthook, lint-staged)
• Offer to migrate from existing tools (ESLint, Prettier)
• Create/merge configuration file (biome.jsonc, .eslintrc.js, etc.)
• Update .vscode/settings.json for editor integration

10. Enable strictNullChecks in tsconfig.json (if TypeScript)

Non-Interactive Setup (CI/Automation)

# Auto-detect settings, skip prompts
bunx ultracite init --quiet

# Specify options explicitly (v7+)
bunx ultracite init \
  --linter biome \
  --pm bun \
  --frameworks react,next \
  --editors vscode \
  --agents cursor,claude \
  --integrations husky \
  --migrate eslint,prettier \
  --quiet

Available flags:

• --linter: Provider selection (biome, eslint, oxlint) - v7+ only
• --pm: Package manager (bun, npm, pnpm, yarn)
• --frameworks: react, next, solid, vue, qwik, angular, remix, svelte
• --editors: vscode, zed
• --agents: cursor, claude, cline, copilot, windsurf, etc.
• --integrations: husky, lefthook, lint-staged
• --migrate: eslint, prettier, biome
• --quiet: Skip all prompts (auto-enabled when CI=true)

Manual Setup (Advanced)

# 1. Install dependencies
bun add -D ultracite @biomejs/biome

# 2. Create biome.jsonc
cat > biome.jsonc << 'EOF'
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core"]
}
EOF

# 3. Create VS Code settings
mkdir -p .vscode
cat > .vscode/settings.json << 'EOF'
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}
EOF

# 4. Enable TypeScript strict mode
# Add to tsconfig.json:
{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

Verify Installation

# Check installation
bunx ultracite doctor

# Expected output:
# ✔ Biome is installed
# ✔ Configuration file found: biome.jsonc
# ✔ Editor integration configured
# ✔ TypeScript strict mode enabled

Configuration

Basic Configuration

File structure:

project-root/
├── biome.jsonc              # Main configuration
├── .vscode/settings.json    # VS Code integration
├── tsconfig.json            # TypeScript config (strictNullChecks required)
└── package.json

Minimal biome.jsonc:

{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core"],

  // Optional: Add framework preset
  // "extends": ["ultracite/core", "ultracite/react"],

  // Optional: Customize rules
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"  // Disable specific rule
      }
    }
  },

  // Optional: Exclude files
  "files": {
    "ignore": ["dist", "build", "coverage", "**/*.generated.ts"]
  }
}

Framework Presets

• ultracite/react: React Hooks, JSX a11y, component best practices
• ultracite/nextjs: React + Next.js App Router, image optimization, document structure
• ultracite/vue: Vue 3 Composition API, template syntax, reactivity
• ultracite/svelte: Svelte 4/5 syntax, reactive declarations

Usage:

{
  "extends": ["ultracite/core", "ultracite/react"]
}

Core Preset

The ultracite/core preset includes 200+ rules across 7 categories:

• Accessibility: ARIA validation, semantic HTML, keyboard navigation
• Correctness: Type safety, unused code removal, exhaustive dependencies
• Performance: Code optimization, barrel file warnings
• Security: Prevents eval(), XSS risks, unsafe patterns
• Style: Consistent patterns, const preference, import organization
• Suspicious: Catches loose equality, debugger statements, typos
• Complexity: Cognitive complexity limits

Formatting defaults: 2 spaces, 80 chars/line, LF endings, single quotes

For detailed framework presets, rule descriptions, and advanced configuration, see: references/configuration-guide.md

Usage

IDE Integration (Recommended)

VS Code Setup:

• Install Biome extension: biomejs.biome
• Verify .vscode/settings.json:

   {
     "editor.defaultFormatter": "biomejs.biome",
     "editor.formatOnSave": true,
     "editor.codeActionsOnSave": {
       "quickfix.biome": "explicit",
       "source.organizeImports.biome": "explicit"
     }
   }

• Disable conflicting extensions (ESLint, Prettier)

Features:

• Auto-format on save
• Auto-fix on save (removes unused imports, fixes order, applies strict equality)
• Format on paste
• Problems panel for unfixable issues
• Quick fixes via lightbulb indicators

CLI Usage

Check code (lint only):

bunx ultracite check
bunx ultracite check src/
bunx ultracite check --diagnostic-level error  # Only errors

Fix code (auto-fix):

bunx ultracite check --write
bunx ultracite check --write src/

Format code (format only):

bunx ultracite format --write
bunx ultracite format --write src/

Package.json scripts:

{
  "scripts": {
    "lint": "ultracite check",
    "lint:fix": "ultracite check --write",
    "format": "ultracite format --write"
  }
}

Git Hook Integrations

Ultracite auto-detects and integrates with:

• Husky: Node.js-based hook manager
• Lefthook: Fast Go-based hook manager
• lint-staged: Runs linters on staged files only

Quick setup:

# Husky
bunx ultracite init --integrations husky

# Lefthook
bunx ultracite init --integrations lefthook

# lint-staged
bunx ultracite init --integrations lint-staged

Example .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

ultracite check --staged --write

For complete Git hook setup guides (Husky, Lefthook, lint-staged), see: references/git-hooks-setup.md

AI Editor Rules

Ultracite generates AI editor rules that teach AI assistants about your linting/formatting standards.

Supported editors:

• Cursor (.cursorrules)
• Claude Code (.windsurfrules)
• GitHub Copilot (.github/copilot-instructions.md)
• Continue.dev (.continuerules)
• Codeium (.codeiumrules)
• Zed (.zedrules)

Generate rules:

bunx ultracite generate-ai-rules
bunx ultracite generate-ai-rules --all  # All editors
bunx ultracite generate-ai-rules --editor=cursor  # Specific editor

For complete AI editor integration guide and customization, see: references/ai-editor-integration.md

Monorepo Support

Ultracite optimizes for monorepos with:

• Shared base configurations
• Package-specific overrides
• Turborepo/Nx caching integration
• Performance optimization for large workspaces

Example monorepo structure:

monorepo/
├── biome.json              # Shared base config
├── apps/
│   └── web/
│       └── biome.json      # Next.js-specific overrides
└── packages/
    └── ui/
        └── biome.json      # React-specific overrides

For complete monorepo setup, Turborepo/Nx integration, and performance tips, see: references/monorepo-configuration.md

Migration from ESLint/Prettier/Biome

Automatic migration:

bunx ultracite migrate eslint
bunx ultracite migrate prettier
bunx ultracite migrate biome

Manual migration:

• Analyze current configuration
• Map rules to Biome equivalents
• Create biome.json with equivalent rules
• Update package.json scripts
• Remove old dependencies
• Test thoroughly

For complete migration guides with detailed rule mappings, see: references/migration-guides.md

Known Limitations

CSS/SCSS: Biome does not lint CSS. Workaround: Use Stylelint

Framework gaps: Limited Angular/Astro support. Workaround: Use ultracite/core + manual rules

ESLint plugins: Many ESLint plugins have no Biome equivalent. Workaround: Run ESLint alongside Ultracite for specific plugins

File types: No Markdown, YAML, HTML linting. Workaround: Use dedicated tools (markdownlint, yamllint, htmlhint)

For complete list of limitations and detailed workarounds, see: references/limitations-and-workarounds.md

Troubleshooting

Common issues:

• VS Code not formatting on save → Install Biome extension, configure settings
• ESLint conflicts → Disable ESLint or run selectively
• Parse errors → Configure JSX support in biome.json
• Pre-commit hooks failing → Use bunx instead of global install
• CI failures → Pin Bun/Node versions, increase memory limit

For complete troubleshooting guide, see: references/troubleshooting.md

Templates & Scripts

Initial Setup Script

See scripts/install-ultracite.sh for automated setup.

Migration Script

See scripts/migrate-to-ultracite.sh for ESLint/Prettier migration.

Example Configurations

See references/ directory for:

• configuration-guide.md: Framework presets and rule details
• git-hooks-setup.md: Husky, Lefthook, lint-staged setup
• ai-editor-integration.md: Cursor, Claude Code, Copilot rules
• monorepo-configuration.md: Turborepo, Nx, pnpm workspaces
• migration-guides.md: ESLint, Prettier, Biome migration
• troubleshooting.md: Common issues and solutions
• limitations-and-workarounds.md: Known gaps and fixes

Package Versions

Current versions (verified 2025-11-27):

• ultracite: latest
• @biomejs/biome: >=1.9.0

Check for updates:

npm view ultracite version
npm view @biomejs/biome version

Update:

bun update ultracite @biomejs/biome

Resources

Official Documentation:

• https://www.ultracite.ai/introduction
• https://www.ultracite.ai/setup
• https://www.ultracite.ai/configuration
• https://biomejs.dev/

Examples:

• https://www.ultracite.ai/examples

Troubleshooting:

• https://www.ultracite.ai/troubleshooting
• https://www.ultracite.ai/faq

Community:

• GitHub Issues: https://github.com/ultracite/ultracite
• Biome Discord: https://discord.gg/biome

When to Load References

Load reference files on-demand based on user questions or task requirements:

references/provider-biome.md: When user asks about:

• Biome provider specifics
• Biome-only configuration
• Biome performance optimization
• Biome preset paths (v7: ultracite/biome/*)
• Biome rule customization

references/provider-eslint.md: When user asks about:

• ESLint provider setup
• ESLint + Prettier + Stylelint integration
• ESLint plugin configuration
• ESLint migration to Ultracite
• Advanced CSS/SCSS linting

references/provider-oxlint.md: When user asks about:

• Oxlint provider setup
• Type-aware linting features
• Oxlint performance benefits
• Oxlint vs Biome comparison
• TypeScript integration

references/v6-migration.md: When user asks about:

• Upgrading from v5 to v6
• Framework preset introduction
• v6 configuration changes
• v6 breaking changes

references/v7-migration.md: When user asks about:

• Upgrading from v6 to v7
• Preset path migration (ultracite/core → ultracite/biome/core)
• Multi-provider setup
• v7 breaking changes
• ultracite doctor command

references/mcp-integration.md: When user asks about:

• MCP server setup
• AI assistant integration via MCP
• Model Context Protocol
• MCP server configuration

references/ai-hooks.md: When user asks about:

• AI hooks setup (distinct from AI rules)
• Auto-format after AI edits
• Editor hook configuration
• Post-edit formatting automation

references/configuration-guide.md: When user asks about:

• Framework presets (React, Next.js, Vue, Svelte)
• Core preset rules (200+ rules breakdown)
• Rule customization methods
• File exclusion patterns
• Advanced configuration

references/git-hooks-setup.md: When user asks about:

• Pre-commit hooks
• Husky integration
• Lefthook integration
• lint-staged setup
• CI/CD integration
• Hook troubleshooting

references/ai-editor-integration.md: When user asks about:

• AI editor rules generation
• Cursor integration
• Claude Code integration
• GitHub Copilot setup
• Custom AI rules
• Editor-specific setup

references/monorepo-configuration.md: When user asks about:

• Monorepo setup
• Turborepo integration
• Nx integration
• Package-specific overrides
• Workspace configuration
• Performance optimization

references/migration-guides.md: When user asks about:

• ESLint migration
• Prettier migration
• Biome migration
• Rule mapping
• Migration checklist
• Post-migration steps

references/troubleshooting.md: When user asks about:

• VS Code issues
• ESLint/Prettier conflicts
• Parse errors
• Pre-commit hook failures
• CI failures
• TypeScript strictness errors
• Installation issues
• Performance problems

references/limitations-and-workarounds.md: When user asks about:

• CSS linting
• Framework support gaps
• ESLint plugin ecosystem
• File type support
• Editor integration
• Migration limitations

Secure Installation

When installing linting/formatting packages, follow supply chain security best practices:

• Block post-install scripts — npm config set ignore-scripts true (or Bun: disabled by default)
• Cooldown period — Wait 7 days for new package versions to be vetted by the community
• Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages

Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

Summary

Ultracite provides a unified linting and formatting solution with multi-provider support:

✅ Use when:

• Starting new projects
• Building with React/Next/Vue/Svelte
• Working in monorepos
• Want consistent formatting without configuration
• Performance matters (Biome/Oxlint providers)
• Need ESLint compatibility (ESLint provider)
• Using AI coding assistants
• Require type-aware linting (Oxlint)

⚠️ Consider alternatives when:

• Need specific ESLint plugins not supported by any provider
• Advanced CSS linting required (though ESLint provider includes Stylelint)
• Legacy framework support needed

Key advantages:

• Multi-provider: Choose Biome (fastest), ESLint (most compatible), or Oxlint (type-aware)
• Version 7: Preset path migration, MCP server, AI hooks, multi-provider architecture
• Version 6: Framework-specific presets (React, Next.js, Vue, Svelte, etc.)
• 10-100x faster than traditional ESLint + Prettier (Biome/Oxlint)
• Zero configuration (200+ rules preconfigured for Biome)
• Framework-specific presets
• AI editor integration + AI hooks
• Git hook support
• TypeScript strict mode enforced

Installation:

bun x ultracite init --linter biome   # Default (v7+)
bun x ultracite init --linter eslint  # ESLint provider (v7+)
bun x ultracite init --linter oxlint  # Oxlint provider (v7+)

Most common workflow:

• Install with bun x ultracite init
• Select framework preset (React, Next.js, etc.)
• Choose Git hook integration (Husky, Lefthook, lint-staged)
• Enable AI editor rules (Cursor, Claude Code, Copilot)
• Optionally migrate from ESLint/Prettier
• Code with auto-formatting on save
• Commit with pre-commit hooks ensuring quality

Remember:

• Always check for existing Git hook managers before installing
• Assess project suitability (scan for ESLint/Prettier/frameworks)
• Recommend or warn based on project characteristics
• Enable strictNullChecks in TypeScript projects
• Use framework-specific presets for best results
• Load reference files on-demand based on user questions