Holistic Linting Skill

This skill embeds comprehensive linting and formatting verification into Claude Code's workflow, preventing the common pattern where code is claimed "production ready" without actually running quality checks.

Purpose

Prevent Claude from:

• Completing tasks without formatting and linting modified files
• Claiming code is "production quality" based on pattern-matching rather than verification
• Assuming only 2 linters exist (mypy + ruff) when projects may have 4+ linting tools
• Suppressing linting errors with # type: ignore or # noqa comments without understanding root causes

Ensure Claude:

• Automatically formats and lints all modified files before task completion
• Reads project-specific linting configuration from CLAUDE.md
• Resolves linting issues systematically using root-cause analysis
• Orchestrates concurrent linting agents when multiple files have issues

When This Skill Applies

This skill applies to all code editing tasks in projects with linting configuration. It provides different behavior based on Claude's role:

For Orchestrators (Interactive Claude Code CLI)

After completing implementation work:

1. Format files - Run formatters on all modified files (ruff format, prettier, etc.)
2. Lint files - Run linters on all modified files concurrently
3. Resolve issues - If linting errors found, launch concurrent linting-root-cause-resolver agents (one per file with issues)
4. Verify resolution - Don't mark task complete until all code smells resolved

For Sub-Agents (Task-delegated agents)

Before completing any task that involved Edit/Write/MultiEdit:

1. Format touched files - Run formatters on files the agent modified
2. Lint touched files - Run linters on files the agent modified
3. Resolve issues directly - Use linting tools directly to fix issues
4. Don't complete - Don't mark task complete until all linting issues in touched files are resolved

How to Use This Skill

Automatic Behavior

This skill modifies Claude's standard workflow to include automatic quality checks:

Before this skill:

[User request] → [Code changes] → [Task complete ✓]

With this skill:

[User request] → [Code changes] → [Format] → [Lint] → [Resolve issues] → [Task complete ✓]

Reading Project Linting Configuration

Before running any linters, check for the ## LINTERS section in the project's CLAUDE.md file:

Grep(pattern="^## LINTERS", path="CLAUDE.md", output_mode="content", -A=50)

If the section exists, use those specifications as the authoritative source for what linters to run.

If the section does not exist, use the /lint init command (see below) to discover and document the project's linters.

Expected CLAUDE.md LINTERS Section Format

## LINTERS

git pre-commit hooks: enabled|disabled pre-commit tool: husky|pre-commit|manual

### Formatters

- markdownlint [*.{md,markdown}]
- ruff format [*.py]
- biome [*.{ts,js,tsx,jsx,json}]
- shfmt [*.{sh,bash,fish,zsh}]
- prettier [*.{md,markdown,mjs,cjs}]

### Static Checking and Linting

- ruff check [*.py]
- mypy [*.py]
- bandit [*.py]
- pyright [*.py]
- markdownlint [*.{md,markdown}]

Running Formatters and Linters

For Python files:

# Format first (auto-fixes trivial issues)
uv run ruff format path/to/file.py

# Then lint (reports substantive issues)
uv run ruff check path/to/file.py
uv run mypy path/to/file.py
uv run pyright path/to/file.py

For JavaScript/TypeScript files:

# Format first
npx prettier --write path/to/file.ts

# Then lint
npx eslint path/to/file.ts

For Shell scripts:

# Format first
shfmt -w path/to/script.sh

# Then lint
shellcheck path/to/script.sh

For Markdown:

# Lint and auto-fix
npx markdownlint-cli2 --fix path/to/file.md

Resolving Linting Issues

For Orchestrators: When linting reveals errors in multiple files, launch concurrent linting-root-cause-resolver agents:

Task(subagent_type="linting-root-cause-resolver",
     description="Fix linting errors in file1.py",
     prompt="...")
Task(subagent_type="linting-root-cause-resolver",
     description="Fix linting errors in file2.py",
     prompt="...")

For Sub-Agents: Use the linting-root-cause-resolver process directly:

1. Investigate the rule using official documentation
2. Trace code flow to understand the issue
3. Generate hypotheses about root causes
4. Implement fixes addressing the actual problem
5. Verify with linting tools

Bundled Resources

Agent: linting-root-cause-resolver

Location: ./agents/linting-root-cause-resolver.md

This agent systematically investigates and resolves linting errors by understanding root causes rather than suppressing them with ignore comments.

To install the agent:

# Install to user scope (~/.claude/agents/)
python holistic-linting/scripts/install-agents.py --scope user

# Install to project scope (<git-root>/.claude/agents/)
python holistic-linting/scripts/install-agents.py --scope project

# Overwrite existing agent file
python holistic-linting/scripts/install-agents.py --scope user --force

Philosophy:

• Linting errors are symptoms of deeper issues
• Never silence errors without understanding them
• Always verify assumptions through investigation
• Prioritize clarity and correctness over quick fixes

Rules Knowledge Base

Comprehensive documentation of linting rules from three major tools:

Ruff Rules (933 rules documented)

Location: ./references/rules/ruff/index.md

Covers all Ruff rule families including:

• E/W (pycodestyle errors and warnings)
• F (Pyflakes logical errors)
• B (flake8-bugbear common bugs)
• S (Bandit security checks)
• I (isort import sorting)
• UP (pyupgrade modern Python patterns)
• And 13 more families

Each rule documents:

• What it prevents (design principle)
• When it's a violation (examples)
• When it's NOT a violation (edge cases)
• Violating code examples
• Resolved code examples
• Configuration options

MyPy Error Codes

Location: ./references/rules/mypy/index.md

Comprehensive type checking error documentation organized by category:

• Attribute access errors
• Name resolution errors
• Function call type checking
• Assignment compatibility
• Collection type checking
• Operator usage
• Import resolution
• Abstract class enforcement
• Async/await patterns

Each error code documents:

• Type safety principle it enforces
• When this is an error (type violations)
• When this is NOT an error (valid patterns)
• Error-producing code examples
• Corrected code examples
• Configuration options (mypy.ini, pyproject.toml)

Bandit Security Checks (65+ checks documented)

Location: ./references/rules/bandit/index.md

Security vulnerability documentation organized by category:

• Credentials and secrets
• Cryptography weaknesses
• SSL/TLS vulnerabilities
• Injection attacks (command, SQL, XML)
• Deserialization risks
• File permissions
• Unsafe functions
• Framework configuration
• Dangerous imports

Each check documents:

• Security risk (what vulnerability it prevents)
• When this is vulnerable (insecure patterns)
• When this is NOT vulnerable (safe usage)
• Vulnerable code examples
• Secure code examples with mitigations
• Severity level (LOW, MEDIUM, HIGH)

Scripts (Coming Soon)

The following scripts will be available in ./scripts/:

1. install-agents.py - Install the linting-root-cause-resolver agent
2. discover-linters.py - Scan project and generate LINTERS section for CLAUDE.md
3. lint-orchestrator.py - Run project linters based on CLAUDE.md configuration

Slash Commands

/lint Command

The /lint slash command provides manual invocation of linting workflows.

Usage:

/lint                    # Lint all files in current directory
/lint path/to/file.py    # Lint specific file
/lint path/to/directory  # Lint all files in directory
/lint init               # Discover linters and update CLAUDE.md
/lint init --force       # Re-discover linters (overwrite existing config)

See /.claude/commands/lint.md for the full command implementation.

Integration with Claude Code Hooks

This skill complements the claude-linting-hook which provides automatic PostToolUse linting via Claude Code hooks. The hook and skill serve different purposes:

claude-linting-hook (PostToolUse hook):

• Triggers automatically after Edit/Write/MultiEdit
• Provides immediate feedback during development
• Blocks on substantive issues
• Runs in hook execution context

holistic-linting skill (Workflow guidance):

• Guides Claude's task completion workflow
• Ensures linting happens before claiming "done"
• Provides rules knowledge base for investigation
• Includes systematic resolution process via linting-root-cause-resolver agent

Use both together for comprehensive linting coverage:

1. Hook catches issues immediately during editing
2. Skill ensures systematic resolution before task completion
3. Knowledge base supports root-cause analysis

Examples

Example 1: Orchestrator completes Python feature implementation

User: "Add authentication middleware to the API"

Claude:
1. [Implements authentication middleware in auth.py]
2. [Implementation complete, now applying holistic-linting skill]
3. Formatting: uv run ruff format auth.py
4. Linting: uv run ruff check auth.py && uv run mypy auth.py
5. [Finds 3 ruff errors, 2 mypy type issues]
6. [Launches 1 linting-root-cause-resolver agent for auth.py]
7. [Agent resolves all 5 issues at root cause]
8. [Verifies: uv run ruff check auth.py && uv run mypy auth.py - clean]
9. Task complete ✓

Example 2: Sub-agent writes Python module

Orchestrator delegates: "Create database connection pool module"

Sub-agent:
1. [Writes db_pool.py with connection logic]
2. [Before completing, applies holistic-linting skill]
3. Formatting: uv run ruff format db_pool.py
4. Linting: uv run ruff check db_pool.py && uv run mypy db_pool.py
5. [Finds 1 mypy error: Missing return type annotation]
6. [Investigates: function should return ConnectionPool]
7. [Fixes: Adds -> ConnectionPool annotation]
8. [Verifies: uv run mypy db_pool.py - clean]
9. Returns to orchestrator with completed, lint-free module ✓

Example 3: Using /lint init to discover project linters

/lint init

[Scanning project configuration...]
✓ Found .pre-commit-config.yaml with 6 hooks
✓ Found pyproject.toml with ruff, mypy, pyright config
✓ Found package.json with eslint, prettier
✓ Git pre-commit hooks: enabled (husky)

[Generated LINTERS section]

## LINTERS

git pre-commit hooks: enabled
pre-commit tool: husky

### Formatters
- ruff format [*.py]
- prettier [*.{ts,tsx,json,md}]

### Static Checking and Linting
- ruff check [*.py]
- mypy [*.py]
- pyright [*.py]
- eslint [*.{ts,tsx}]
- markdownlint [*.md]

[Appended to CLAUDE.md ✓]

Best Practices

1. Always read CLAUDE.md LINTERS section first - Don't assume which linters are available
2. Format before linting - Formatters auto-fix trivial issues (end-of-file, whitespace)
3. Run linters concurrently - Use parallel execution for multiple files or multiple linters
4. Use the rules knowledge base - Reference official rule documentation when investigating
5. Never suppress without understanding - Don't add # type: ignore or # noqa without root cause analysis
6. Orchestrators delegate, sub-agents resolve - Orchestrators launch agents for multi-file issues, sub-agents fix their own files
7. Verify after fixes - Always re-run linters to confirm issues are resolved

Troubleshooting

Problem: "I don't know which linters this project uses" Solution: Run /lint init to scan and document project linters

Problem: "Linting errors but I don't understand the rule" Solution: Reference the rules knowledge base at ./references/rules/{ruff,mypy,bandit}/index.md

Problem: "Multiple files with linting errors" Solution: If orchestrator, launch concurrent linting-root-cause-resolver agents (one per file). If sub-agent, resolve each file sequentially.

Problem: "Linter not found (command not available)" Solution: Check that linters are installed. Use uv run <tool> for Python tools to ensure virtual environment activation.

Problem: "False positive linting error" Solution: Investigate using the rule's documentation. If truly a false positive, configure the rule in pyproject.toml/config file rather than using ignore comments.

Skill Activation

This skill is automatically loaded when installed in ~/.claude/skills/holistic-linting.

To manually reference this skill in a session:

Activate the holistic-linting skill: Skill(command: "holistic-linting")

Related Skills

• python3-development - Modern Python development patterns and best practices
• uv - Python package and project management with uv