---

name: ruff description: This skill should be used when users need to lint, format, or validate Python code using the Ruff command-line tool. Use this skill for tasks involving Python code quality checks, automatic code formatting, enforcing style rules (PEP 8), identifying bugs and security issues, or modernizing Python code. This skill should be invoked PROACTIVELY whenever Python code is written or modified to ensure code quality.

Ruff Skill

Contents

• Proactive Usage
• Quick Reference
• Linting Workflow
• Formatting Workflow
• Rule Selection
• Troubleshooting
• References

Proactive Usage

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

Standard Workflow

Copy# 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

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

Quick Reference

Commands

Common Flags

Linting Workflow

1. Check for Issues

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

2. Auto-fix Safe Issues

Copyuv run ruff check --fix .

3. Review Unsafe Fixes

Copyuv 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:

Copyimport unused_module  # noqa: F401

Formatting Workflow

1. Format Code

Copyuv run ruff format .

2. Check Without Modifying (CI/CD)

Copyuv run ruff format --check .

3. Preview Changes

Copyuv run ruff format --diff .

Rule Selection

Essential Rules (Start Here)

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

Recommended Rules

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

Security Rules

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

Project Configuration

Basic pyproject.toml

Copy[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

Copy# 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:

   Copyuv run ruff check --select=F,E .
   

2. Add noqa comments to existing violations:

   Copyuv run ruff check --add-noqa .
   

3. Fix auto-fixable issues first:

   Copyuv run ruff check --fix .
   

4. 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:

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

Output Formats for CI

Copyuv 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 - Complete rule descriptions by category
• Configuration Reference - 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