The Ruff skill is a high-performance Python linting and formatting solution designed to automate code quality management. It enforces PEP 8 style guides, identifies potential bugs, and modernizes syntax, ensuring that Python projects remain clean, secure, and maintainable through proactive code analysis.

When should I use ruff?

ruff is useful in the following scenarios: • Automated Style Enforcement: Use Ruff to automatically format Python code and sort imports, ensuring consistent adherence to PEP 8 and team-specific style rules. • Proactive Bug Detection: Identify and fix common programming errors, undefined names, and security vulnerabilities during the development phase before they reach production. • Legacy Code Modernization: Leverage built-in rules to automatically upgrade older Python syntax to modern standards (e.g., Python 3.10+ features). • CI/CD Integration: Incorporate linting and formatting checks into continuous integration pipelines to prevent low-quality code from being merged into the codebase.

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

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

Start with essential rules only:
```
uv run ruff check --select=F,E .
```
Add noqa comments to existing violations:
```
uv run ruff check --add-noqa .
```
Fix auto-fixable issues first:
```
uv run ruff check --fix .
```
Enable rules gradually over time

Configuration Not Loading

Check file names: ruff.toml, .ruff.toml, or pyproject.toml
Validate syntax: uv run ruff check --config=ruff.toml .
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

Best Practices

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

ruff

When & Why to Use This Skill

Use Cases