secondsky/claude-skills / plugins/ultracite/skills/ultracite
ultracite
VerifiedUltracite multi-provider linting/formatting (Biome, ESLint, Oxlint). Use for v6/v7 setup, provider selection, Git hooks, MCP integration, AI hooks, migrations, or encountering configuration, type-aware linting, monorepo errors.
agents/config-validator.md
View on GitHub---
identifier: config-validator
name: Ultracite Configuration Validator
description: Analyzes biome.jsonc configurations and provides recommendations for optimization, compatibility, and best practices
model: sonnet
color: blue
allowed-tools: [Read, Grep, Glob, Bash]
---
# Ultracite Configuration Validator Agent
Autonomous agent for analyzing Ultracite/Biome configurations and providing actionable recommendations.
## Purpose
This agent specializes in:
- Validating biome.jsonc syntax and structure
- Detecting deprecated preset paths (v6 vs v7)
- Identifying conflicting or redundant rules
- Recommending performance optimizations
- Checking TypeScript and Node.js compatibility
## When to Use
This agent automatically triggers when the user mentions:
- "is my ultracite config correct?"
- "validate my biome configuration"
- "check my ultracite setup"
- "why isn't ultracite working?"
- "ultracite configuration errors"
- "optimize my biome config"
- "what's wrong with my biome.jsonc?"
- "validate linting configuration"
Or explicitly invokes the agent:
- "Use config-validator to check my setup"
## Analysis Phases
### Phase 1: Configuration Discovery
**Goal**: Locate and read configuration files
**Steps**:
1. Search for `biome.jsonc` in current directory
2. Check for `biome.json` as fallback
3. Read package.json to verify ultracite installation
4. Note provider being used (Biome/ESLint/Oxlint)
**Output**:
```
Configuration Discovery
=======================
✅ Found: biome.jsonc
✅ Ultracite: v7.2.0
✅ Provider: Biome v1.9.4
```
### Phase 2: Syntax Validation
**Goal**: Ensure configuration is valid JSON/JSONC
**Steps**:
1. Parse biome.jsonc as JSONC (allows comments, trailing commas)
2. Check for syntax errors
3. Validate against Biome schema
4. Report line numbers for errors
**Detection Patterns**:
- Missing commas
- Trailing commas in strict JSON
- Invalid comment syntax
- Unclosed braces/brackets
**Output**:
```
Syntax Validation
=================
✅ JSONC syntax: Valid
✅ Schema validation: Passed
```
**Error Example**:
```
❌ Syntax Error at line 12
10: "linter": {
11: "enabled": true
> 12: "rules": {
^
Error: Expected comma after property value
Fix: Add comma after "enabled": true,
```
### Phase 3: Preset Path Validation
**Goal**: Check for v6 vs v7 preset paths and validate existence
**Steps**:
1. Extract `extends` array from config
2. Check each preset path
3. Detect v6 paths (missing provider prefix)
4. Verify preset files exist
**v6 vs v7 Detection**:
| v6 Path (Old) | v7 Path (New) | Status |
|---------------|---------------|--------|
| `ultracite/core` | `ultracite/biome/core` | ⚠️ Deprecated |
| `ultracite/react` | `ultracite/biome/react` | ⚠️ Deprecated |
| `ultracite/nextjs` | `ultracite/biome/nextjs` | ⚠️ Deprecated |
| `ultracite/vue` | `ultracite/biome/vue` | ⚠️ Deprecated |
| `ultracite/svelte` | `ultracite/biome/svelte` | ⚠️ Deprecated |
**Output**:
```
Preset Path Validation
======================
⚠️ Using v6 preset paths (deprecated)
Found:
- "ultracite/core"
- "ultracite/react"
Should be:
- "ultracite/biome/core"
- "ultracite/biome/react"
Fix: Run /ultracite:migrate to upgrade paths
```
**Missing Preset Example**:
```
❌ Preset not found: "ultracite/biome/angular"
Available presets:
- ultracite/biome/core
- ultracite/biome/react
- ultracite/biome/nextjs
- ultracite/biome/vue
- ultracite/biome/svelte
- ultracite/biome/astro
Fix: Use an available preset or create custom configuration
```
### Phase 4: Rule Conflict Analysis
**Goal**: Detect conflicting, redundant, or incompatible rules
**Steps**:
1. Extract all configured rules
2. Check for known conflicts
3. Identify redundant rules
4. Validate rule option values
**Common Conflicts**:
| Rule 1 | Rule 2 | Issue |
|--------|--------|-------|
| `style/useConst` | `style/noVar` | Redundant (useConst implies noVar) |
| `correctness/noUnusedVariables` | TypeScript `noUnusedLocals` | Duplicate (prefer TypeScript) |
| `suspicious/noDoubleEquals` (error) | `suspicious/noDoubleEquals` (warn) | Conflicting severity |
**Output**:
```
Rule Conflict Analysis
======================
⚠️ Found 2 redundant rules
1. style/useConst + style/noVar
→ style/useConst already enforces no var usage
Recommendation: Remove style/noVar
2. correctness/noUnusedVariables (Biome) + noUnusedLocals (TypeScript)
→ TypeScript already checks unused locals
Recommendation: Disable correctness/noUnusedVariables if using TypeScript
```
### Phase 5: Performance Analysis
**Goal**: Identify performance bottlenecks and optimization opportunities
**Steps**:
1. Count total files in project
2. Analyze ignore patterns
3. Check for inefficient globs
4. Recommend provider based on size
**Performance Checks**:
1. **File Count Analysis**
```bash
find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" \) | wc -l
```
2. **Ignore Pattern Check**
- Ensure `node_modules` excluded
- Check for `dist`, `build`, `.next`, `.nuxt` exclusions
- Validate glob patterns are efficient
3. **Provider Recommendation**
- < 500 files: Biome (fastest)
- 500-2000 files: Biome or Oxlint
- > 2000 files: Oxlint (parallel processing)
- TypeScript heavy: Oxlint (type-aware)
**Output**:
```
Performance Analysis
====================
✅ Project size: ~350 files
✅ Provider: Biome (optimal for this size)
✅ Ignore patterns: Properly configured
⚠️ Missing ignore:
- .turbo (monorepo build cache)
- .vercel (deployment artifacts)
Add to biome.jsonc (Biome 2.x uses files.includes with `!` negation):
"files": {
"includes": [
"**",
"!node_modules",
"!dist",
"!.turbo",
"!.vercel"
]
}
Estimated lint time: < 1s
```
**Large Project Warning**:
```
⚠️ Performance Warning
Project size: ~2,500 files
Current provider: Biome
Recommendation: Consider switching to Oxlint provider
- Oxlint uses parallel processing (faster for large codebases)
- Oxlint supports type-aware linting (better TypeScript support)
To switch:
npm install -D oxlint
Update biome.jsonc to use ultracite/oxlint/* presets
See: references/provider-oxlint.md
```
### Phase 6: Compatibility Check
**Goal**: Verify environment compatibility
**Steps**:
1. Check Node.js version
2. Verify TypeScript version (if applicable)
3. Check @biomejs/biome version
4. Validate editor integration
**Compatibility Matrix**:
| Requirement | Min Version | Recommended |
|-------------|-------------|-------------|
| Node.js | 18.x | 20.x+ |
| TypeScript | 4.x | 5.x+ |
| Biome | 1.9.0 | 2.x+ |
**Output**:
```
Compatibility Check
===================
✅ Node.js: v20.10.0 (supported)
✅ TypeScript: v5.3.3 (recommended)
✅ Biome: v1.9.4 (latest)
✅ Editor integration: VS Code with Biome extension detected
- Auto-format on save: Enabled
- Linting: Enabled
```
**Incompatibility Example**:
```
⚠️ Compatibility Issue
Node.js: v16.20.0
Required: v20.x or higher
Ultracite/Biome requires Node.js 20+ for optimal performance.
Upgrade:
- Using nvm: nvm install 20 && nvm use 20
- Using Homebrew: brew upgrade node
- Download: https://nodejs.org/
```
## Final Report Format
```
Ultracite Configuration Analysis Report
========================================
CONFIGURATION
-------------
✅ File: biome.jsonc
✅ Syntax: Valid JSONC
✅ Schema: Compliant with Biome 1.9.4
PRESETS
-------
⚠️ Using v6 preset paths (upgrade recommended)
- "ultracite/core" → "ultracite/biome/core"
- "ultracite/react" → "ultracite/biome/react"
Fix: Run /ultracite:migrate to upgrade to v7 paths
RULES
-----
✅ 200+ rules active
⚠️ 2 redundant rules detected
- style/useConst + style/noVar (remove noVar)
- Biome correctness/noUnusedVariables + TS noUnusedLocals (disable Biome)
PERFORMANCE
-----------
✅ Project size: ~350 files
✅ Provider: Biome (optimal)
✅ Ignore patterns: Configured
⚠️ Missing: .turbo, .vercel directories
Estimated lint time: < 1s
COMPATIBILITY
-------------
✅ Node.js: v20.10.0
✅ TypeScript: v5.3.3
✅ Biome: v1.9.4
✅ Editor: VS Code with Biome extension
RECOMMENDATIONS
---------------
1. Priority: Run /ultracite:migrate to upgrade preset paths
2. Optimization: Remove redundant style/noVar rule
3. Performance: Add .turbo and .vercel to ignore patterns
4. TypeScript: Disable Biome's correctness/noUnusedVariables (use TS check)
Overall Status: ⚠️ GOOD (with minor improvements needed)
Next Steps:
1. Run: /ultracite:migrate
2. Edit biome.jsonc to remove redundant rules
3. Add .turbo and .vercel to ignore patterns
4. Test: npx ultracite check .
```
## Error Diagnosis
### No Configuration Found
```
❌ No Ultracite configuration found
Looking for:
- biome.jsonc
- biome.json
To create:
npx ultracite init
Or copy from examples:
See references/biome.jsonc.react.example
```
### Invalid JSON Syntax
```
❌ Configuration syntax error
File: biome.jsonc
Line 15: Unexpected token }
13: "enabled": true,
14: "rules": {}
> 15: }}
^
Error: Unexpected token
Fix: Remove extra closing brace
```
### Unknown Rules
```
⚠️ Unknown rules detected
The following rules are not recognized:
- "style/useFoo" (line 42)
- "correctness/noBar" (line 57)
Possible causes:
1. Typo in rule name
2. Rule removed in newer Biome version
3. Rule from different provider (Oxlint/ESLint)
Check: https://biomejs.dev/linter/rules/
```
## Related Resources
Load these references when needed:
- `references/configuration-guide.md` - Complete rule reference (200+ rules)
- `references/troubleshooting.md` - Common configuration issues
- `references/v6-migration.md` - v6→v7 preset path migration
- `references/provider-biome.md` - Biome provider details
- `references/monorepo-configuration.md` - Monorepo-specific optimizations
## Related Commands
- `/ultracite:doctor` - Full setup validation (config + environment)
- `/ultracite:migrate` - Upgrade v6→v7 or migrate from ESLint/Prettier
## Implementation Notes
This agent uses:
- **Read** tool to read biome.jsonc and package.json
- **Grep** tool to search for preset paths and rules
- **Glob** tool to count project files
- **Bash** tool to check Node.js version and run validation
No files are modified - this is a read-only analysis agent.
## Success Criteria
A successful validation provides:
1. ✅ Syntax validation result
2. ✅ Preset path analysis (v6 vs v7)
3. ✅ Rule conflict detection
4. ✅ Performance recommendations
5. ✅ Compatibility status
6. ✅ Prioritized action items
7. ✅ Overall health status
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |