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

# 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

Command	Purpose
uv run ruff check .	Lint code
uv run ruff check --fix .	Fix auto-fixable issues
uv run ruff format .	Format code
uv run ruff format --check .	Check formatting
uv run ruff check --diff .	Preview fixes

Common Flags

Flag	Effect
--fix	Auto-fix issues
--unsafe-fixes	Apply risky fixes
--diff	Show changes without applying
--select E,F	Check specific rules
--ignore E501	Skip specific rules
--statistics	Show issue counts
--watch	Continuous linting

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"]

Prefix	Source	Purpose
F	Pyflakes	Errors, undefined names
E	pycodestyle	PEP 8 errors
I	isort	Import sorting

Recommended Rules

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

Prefix	Source	Purpose
W	pycodestyle	PEP 8 warnings
UP	pyupgrade	Modernize syntax
B	bugbear	Likely bugs
SIM	simplify	Simplification

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

Pattern	Common Ignores	Reason
tests/**/*.py	S101	Allow assert
__init__.py	F401	Allow unused imports
scripts/*.py	T201	Allow print

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:

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

2. Add noqa comments to existing violations:

   uv run ruff check --add-noqa .
   

3. Fix auto-fixable issues first:

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

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