ruff Integration Skill | Agent Skills

ruff Integration

Integrate ruff into editors, pre-commit hooks, and CI/CD pipelines.

When to Use This Skill

| Use this skill when... | Use ruff-linting instead when... | Use ruff-formatting instead when... | |------------------------|----------------------------------|-------------------------------------| | Setting up VS Code / editor | Configuring lint rules | Configuring format options | | Adding pre-commit hooks | Selecting/ignoring rules | Quote style, line length | | Adding ruff to CI/CD | Understanding rule categories | Format differences | | Docker/build integration | Fixing lint violations | Checking format compliance |

VS Code Setup

// .vscode/settings.json
{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "ruff.lint.args": ["--select=E,F,B,I"],
  "ruff.importStrategy": "fromEnvironment"
}

# Install extension
code --install-extension charliermarsh.ruff

Pre-commit Integration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.0
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

pre-commit install           # Install hooks
pre-commit run --all-files   # Run manually
pre-commit autoupdate        # Update versions

GitHub Actions CI

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: 'check --output-format github'

Separate lint + format checks:

jobs:
  ruff-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff check --output-format github

  ruff-format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff format --check --diff

Configuration Hierarchy

Command-line arguments (highest priority)
Editor LSP settings
ruff.toml in current directory
pyproject.toml in current directory
Parent directory configs (recursive)
User config: ~/.config/ruff/ruff.toml
Ruff defaults (lowest priority)

Best Practices

Editor: Enable format-on-save, use project-specific .vscode/settings.json
Pre-commit: Run ruff-check --fix first, then ruff-format
CI/CD: Use --output-format github for PR annotations
Performance: Cache ruff in CI, run on changed files only in pre-commit
Team: Commit editor/pre-commit configs to version control

Agentic Optimizations

| Context | Command | |---------|---------| | Quick lint check | ruff check --output-format github | | Format check | ruff format --check --diff | | Auto-fix all | ruff check --fix && ruff format | | Errors only | ruff check --select E | | CI annotations | ruff check --output-format github | | JSON output | ruff check --output-format json | | Specific files | ruff check --diff path/to/file.py |

Quick Reference

# Editor
code --install-extension charliermarsh.ruff

# Pre-commit
pre-commit install && pre-commit run --all-files

# CI (GitHub Actions)
uses: astral-sh/ruff-action@v3

# Docker
docker run -v .:/app ghcr.io/astral-sh/ruff:0.14.0-alpine check /app

For editor configs (Neovim, Zed, Helix), GitLab/CircleCI/Jenkins CI, build system integration, Docker setup, LSP configuration, and migration guides, see REFERENCE.md.

Agent Skills: ruff Integration

Install this agent skill to your local

Skill Files