Code Linting Skill

Unified linting workflow for Python (ruff) and JavaScript (Biome). Covers check, format, and auto-fix for both languages. Only handles Python and JavaScript/TypeScript -- complex logic issues and other languages are out of scope.

Reference Loading Table

Signal	Load These Files	Why
Python violations, ruff rules, F401/E711/B006/UP errors	`ruff-rules-reference.md`	Routes to the matching deep reference
ruff not found, pyproject.toml config, ruff version differences	`ruff-rules-reference.md`	Routes to the matching deep reference
JavaScript/TypeScript violations, Biome rules, noVar/useConst/noDoubleEquals	`biome-rules-reference.md`	Routes to the matching deep reference
biome not found, biome.json config, migrating from ESLint	`biome-rules-reference.md`	Routes to the matching deep reference
Linting CI failures, format check vs lint check differences	`biome-rules-reference.md`	Routes to the matching deep reference

Instructions

1. Read Project Configuration

Before running any linter, read the repository's CLAUDE.md for project-specific linting rules -- those override every default below. Then locate the project's linter config files (pyproject.toml for ruff, biome.json for Biome). All linter invocations must use these configs as-is; never override line width, rule sets, or other project settings.

2. Detect Languages and Run Checks

When a project contains both Python and JavaScript/TypeScript, lint both unless the user explicitly requests a single language. Run the check command first to see what violations exist:

# Python -- use project venv when available
ruff check .
# or: ./venv/bin/ruff check .

# JavaScript/TypeScript
npx @biomejs/biome check src/

Always display the complete linter output. Never summarize results as "no issues found" or describe output secondhand -- show the actual command output so the user can see every error, warning, and style issue together.

3. Review Output Before Fixing

Read the full output and understand what violations exist and their severity before applying any fixes. Jumping straight to --fix without reviewing risks auto-removing imports that are still needed or making changes that reduce readability.

4. Apply Auto-Fixes

Apply --fix for safe categories: formatting, import ordering, and style issues that the linter can correct mechanically.

# Python
ruff check --fix .
ruff format .

# JavaScript/TypeScript
npx @biomejs/biome check --write src/
npx @biomejs/biome format --write src/

Only run the linters and fixes that were requested. Do not add custom rules, configuration changes, or additional tooling unless the user explicitly asks.

5. Review the Diff

After auto-fix, review the diff to verify changes are correct and safe:

git diff

Auto-fixes can occasionally remove imports that are still needed, reformat code in ways that hurt readability, or introduce subtle bugs through variable shadowing changes. Revert any problematic auto-fixes before proceeding.

6. Fix Remaining Issues Manually

For violations that cannot be auto-fixed, explain each one and how to resolve it:

Python common fixes:

Unused import (F401): Remove or use the import
Import order (I001): Run ruff check --fix
Line too long (E501): Break into multiple lines or adjust line-length config

JavaScript common fixes:

noVar: Replace var with let/const
useConst: Use const for unchanging values
noDoubleEquals: Use === instead of ==

7. Verify Before Commit

Run the linter one final time to confirm zero violations before suggesting a commit:

ruff check .
ruff format --check .
npx @biomejs/biome check src/

Report output factually -- no self-congratulation, just the command results.

8. Clean Up

Remove any temporary lint report files or cache files created during execution.

Combined Commands (if Makefile configured)

make lint       # Check both Python and JS
make lint-fix   # Fix both Python and JS

Configuration Reference

Tool	Config	Typical Line Width
ruff	pyproject.toml	88-120
biome	biome.json	80-120

Optional Modes

Strict mode: Treat warnings as errors (fail on any issue) -- enable when requested
Format only: Skip linting, only run formatting -- enable when requested
Ignore specific rules: Disable particular lint rules for edge cases -- enable when requested

Error Handling

Error: "ruff not found"

Cause: Virtual environment not activated or ruff not installed Solution:

Use virtual environment path: ./venv/bin/ruff or ./env/bin/ruff
Or install globally: pip install ruff
Or use pipx: pipx run ruff check .

Error: "biome not found"

Cause: Biome not installed in project Solution: Run npx @biomejs/biome to use npx-based execution

Error: "Configuration file not found"

Cause: Running from wrong directory Solution: cd to project root where pyproject.toml/biome.json exist

Reference Loading

Load these files when the task involves the corresponding domain:

Task type	Reference file
Python violations, ruff rules, F401/E711/B006/UP errors	`references/ruff-rules-reference.md`
ruff not found, pyproject.toml config, ruff version differences	`references/ruff-rules-reference.md`
JavaScript/TypeScript violations, Biome rules, noVar/useConst/noDoubleEquals	`references/biome-rules-reference.md`
biome not found, biome.json config, migrating from ESLint	`references/biome-rules-reference.md`
Linting CI failures, format check vs lint check differences	`references/ruff-rules-reference.md` + `references/biome-rules-reference.md`

code-linting