Ruff Skill

Contents

• [Proactive Usage](#proactive-usage)
• [Quick Reference](#quick-reference)
• [Linting Workflow](#linting-workflow)
• [Formatting Workflow](#formatting-workflow)
• [Rule Selection](#rule-selection)
• [Troubleshooting](#troubleshooting)
• [References](#references)

Proactive Usage

IMPORTANT: Use this skill proactively after writing or modifying Python code.

Standard Workflow

# Step 1: Format the code
uv run ruff format .

# Step 2: Fix auto-fixable linting issues
uv run ruff check --fix .

# Step 3: Report remaining issues
uv run ruff check .

Project Commands

just fmt-python    # Format Python code
just lint-python   # Lint Python code

Quick Reference

Commands

Common Flags

Linting Workflow

1. Check for Issues

uv run ruff check .                    # All files
uv run ruff check src/                 # Directory
uv run ruff check script.py            # Single file

2. Auto-fix Safe Issues

uv run ruff check --fix .

3. Review Unsafe Fixes

uv run ruff check --diff --unsafe-fixes .   # Preview
uv run ruff check --fix --unsafe-fixes .    # Apply

4. Address Remaining Issues

Fix manually or suppress with # noqa:

import unused_module  # noqa: F401

Formatting Workflow

1. Format Code

uv run ruff format .

2. Check Without Modifying (CI/CD)

uv run ruff format --check .

3. Preview Changes

uv run ruff format --diff .

Rule Selection

Essential Rules (Start Here)

[tool.ruff]
select = ["F", "E", "I"]

Recommended Rules

[tool.ruff]
select = ["F", "E", "I", "W", "UP", "B", "SIM"]

Security Rules

[tool.ruff]
extend-select = ["S"]

Project Configuration

Basic pyproject.toml

[tool.ruff]
line-length = 100
target-version = "py311"

select = ["E", "F", "I", "B", "UP"]
ignore = ["E501"]

[tool.ruff.per-file-ignores]
"tests/**/*.py" = ["S101"]
"__init__.py" = ["F401"]

[tool.ruff.format]
quote-style = "double"

Per-file Ignores

Inline Suppression

# Ignore all rules for line
import os  # noqa

# Ignore specific rule
import os  # noqa: F401

# Ignore for entire file (at top)
# ruff: noqa: F401

Troubleshooting

Too Many Issues

1. Start with essential rules only:

``bash uv run ruff check --select=F,E . ``

1. Add noqa comments to existing violations:

``bash uv run ruff check --add-noqa . ``

1. Fix auto-fixable issues first:

``bash uv run ruff check --fix . ``

1. Enable rules gradually over time

Configuration Not Loading

1. Check file names: ruff.toml, .ruff.toml, or pyproject.toml
2. Validate syntax: uv run ruff check --config=ruff.toml .
3. Check for conflicts in parent directories

Formatter vs Linter Conflicts

Run formatter before linter to avoid conflicts:

uv run ruff format .
uv run ruff check --fix .

Output Formats for CI

uv run ruff check --output-format=github .   # GitHub Actions
uv run ruff check --output-format=gitlab .   # GitLab CI
uv run ruff check --output-format=json .     # JSON

References

Project References

• [Rules Reference](references/rules.md) - Complete rule descriptions by category
• [Configuration Reference](references/configuration.md) - Config templates and options

External Resources

• Ruff Documentation
• Linter Rules
• Formatter Docs
• Configuration

Best Practices

1. Format first - Run ruff format before ruff check
2. Use --fix liberally - Most auto-fixes are safe
3. Review unsafe fixes - Always check --unsafe-fixes changes
4. Start simple - Begin with F, E, I rules; expand gradually
5. Configure CI/CD - Enforce checks in continuous integration
6. Document exceptions - Comment why rules are disabled