Ruff (Python Linter) — SKILL.md

---
name: "Ruff (Python Linter)"
description: "Skill for Ruff (Python Linter) — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["ruff", "dev", "auto-generated"]
---

# Ruff (Python Linter)

---
name: Ruff Python Linter
description: Use when you need to lint, format, and fix Python code issues. Ruff is an extremely fast Python linter and code formatter written in Rust that combines the functionality of flake8, isort, pydocstyle, and more.
metadata:
  author: skynet
  version: 1.0.0
category: dev
---

# Ruff Python Linter

## Overview
Ruff is an extremely fast Python linter and code formatter that replaces multiple tools (flake8, isort, pydocstyle, etc.) with a single, unified interface. It's 10-100x faster than existing Python linters.

## Installation

```bash
# Install via pip
pip install ruff

# Install via conda
conda install -c conda-forge ruff

# Install via homebrew (macOS)
brew install ruff
```

## Basic Usage

### Linting Commands

```bash
# Lint current directory
ruff check .

# Lint specific file
ruff check src/main.py

# Lint with auto-fix
ruff check --fix .

# Show fixes without applying
ruff check --diff .

# Lint and show rule codes
ruff check --show-source .
```

### Formatting Commands

```bash
# Format code (like black)
ruff format .

# Check formatting without applying
ruff format --check .

# Show diff of formatting changes
ruff format --diff .
```

## Configuration

### pyproject.toml Configuration

```toml
[tool.ruff]
# Exclude a variety of commonly ignored directories
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".git-rewrite",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".pytype",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "venv",
]

# Set the maximum line length
line-length = 88

# Assume Python 3.8+
target-version = "py38"

[tool.ruff.lint]
# Enable specific rule sets
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # Pyflakes
    "I",    # isort
    "B",    # flake8-bugbear
    "C4",   # flake8-comprehensions
    "UP",   # pyupgrade
]

# Disable specific rules
ignore = [
    "E501",  # line too long
    "B008",  # do not perform function calls in argument defaults
]

# Allow fix for all enabled rules
fixable = ["ALL"]
unfixable = []

# Allow unused variables when underscore-prefixed
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

[tool.ruff.format]
# Use double quotes for strings
quote-style = "double"

# Indent with spaces, rather than tabs
indent-style = "space"

# Respect magic trailing comma
skip-magic-trailing-comma = false

# Automatically detect the appropriate line ending
line-ending = "auto"
```

### Command Line Rule Selection

```bash
# Enable specific rules
ruff check --select E,W,F .

# Disable specific rules
ruff check --ignore E501,W503 .

# Enable aggressive rules
ruff check --select ALL --ignore E501 .

# Check only imports (isort functionality)
ruff check --select I .
```

## Common Workflows

### CI/CD Integration

```yaml
# GitHub Actions example
- name: Lint with Ruff
  run: |
    pip install ruff
    ruff check .
    ruff format --check .
```

### Pre-commit Hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.6
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format
```

### Migration from Other Tools

```bash
# Replace flake8
ruff check . --select E,W,F

# Replace isort
ruff check . --select I --fix

# Replace black (formatting)
ruff format .

# Replace multiple tools
ruff check . --select E,W,F,I,B,C4,UP --fix
ruff format .
```

## Decision Trees

### When to Use Different Commands
```
Need to check code quality?
├── Just check issues → ruff check .
├── Check and fix automatically → ruff check --fix .
└── Check formatting only → ruff format --check .

Setting up new project?
├── Start with basics → --select E,W,F
├── Add import sorting → --select E,W,F,I
└── Full setup → --select E,W,F,I,B,C4,UP

Performance issues?
├── Exclude large directories → Add to exclude list
├── Target specific files → ruff check src/ tests/
└── Use specific rules only → --select F,E
```

### Rule Selection Strategy
```
Code maturity level?
├── New project → --select E,W,F,I (basics)
├── Mature project → --select E,W,F,I,B,C4,UP
└── Legacy project → Start with F only, gradually add more

Team experience?
├── Beginner → Focus on E,W,F
├── Intermediate → Add I,B,C4
└── Advanced → Consider ALL with selective ignores
```

## Advanced Features

### Custom Rule Configuration

```bash
# Show all available rules
ruff linter

# Explain specific rule
ruff rule E501

# Check specific rule across codebase
ruff check --select E501 .
```

### Integration with Editors

```bash
# Generate VS Code settings
echo '{
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "none",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}' > .vscode/settings.json
```

### Performance Optimization

```bash
# Cache results for faster subsequent runs
ruff check --cache-dir .ruff_cache .

# Parallel processing (default behavior)
ruff check . --statistics

# Target specific Python version
ruff check . --target-version py311
```

## Troubleshooting

### Common Errors and Solutions

**Error**: `ruff: command not found`
```bash
# Solution: Install ruff
pip install ruff
# or
pip install --user ruff
export PATH="$HOME/.local/bin:$PATH"
```

**Error**: `F401 'module' imported but unused`
```bash
# Solution: Remove unused imports or mark as intentional
# Option 1: Remove the import
# Option 2: Use noqa comment
import unused_module  # noqa: F401
# Option 3: Use underscore prefix
import unused_module as _unused_module
```

**Error**: `E501 line too long`
```bash
# Solution: Configure line length or ignore
# Option 1: In pyproject.toml
[tool.ruff]
line-length = 120

# Option 2: Ignore the rule
ruff check --ignore E501 .
```

**Error**: `I001 Import block is un-sorted or un-formatted`
```bash
# Solution: Auto-fix import sorting
ruff check --select I --fix .

# Or configure isort-style settings
[tool.ruff.lint.isort]
known-first-party = ["mypackage"]
```

**Error**: Configuration not being read
```bash
# Check configuration discovery
ruff check --show-settings .

# Verify file location and syntax
ruff check . --config pyproject.toml
```

### Performance Issues

```bash
# Profile performance
ruff check . --statistics

# Reduce scope for large codebases
ruff check src/ --exclude "src/generated/"

# Use minimal rule set for speed
ruff check . --select F
```

### Integration Issues

```bash
# Test pre-commit setup
pre-commit run ruff --all-files

# Check editor integration
ruff check --output-format=json .

# Verify CI compatibility
ruff check . --format=github
```