MCPInstall

ruff-linting

by laurigates

Python linting with ruff. Fast linting, rule selection, auto-fixing, and config. Use when checking Python code quality, enforcing standards, or finding bugs.

Installs
466
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/laurigates/claude-plugins --skill ruff-linting
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads ruff-linting automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

ruff Linting

Expert knowledge for using ruff check as an extremely fast Python linter with comprehensive rule support and automatic fixing.

When to Use This Skill

Use this skill when...Use a focused sibling instead when...
Running ruff check, selecting rule sets, or auto-fixing lint violationsRunning ruff format to enforce code style — use ruff-formatting
Configuring [tool.ruff.lint] rules and per-file ignores in pyproject.tomlComparing ruff against type-checkers and formatters at a stack level — use python-code-quality
Wiring ruff into editors, pre-commit, CI/CD, Docker, or build systemsSee the quick forms in CI/CD Integration below; full editor/CI/Docker/migration recipes in REFERENCE.md
Migrating from Flake8/pylint/isort/pyupgrade to ruff's combined rule setRunning ruff format to enforce code style — use ruff-formatting

Core Expertise

ruff Advantages

  • Extremely fast (10-100x faster than Flake8)
  • Written in Rust for performance
  • Replaces multiple tools (Flake8, pylint, isort, pyupgrade, etc.)
  • Auto-fix capabilities for many rules
  • Compatible with existing configurations
  • Over 800 built-in rules

Basic Usage

Simple Linting

# Lint current directory
ruff check

# Lint specific files or directories
ruff check path/to/file.py
ruff check src/ tests/

# IMPORTANT: Pass directory as parameter to stay in repo root
# ✅ Good
ruff check services/orchestrator

# ❌ Bad
cd services/orchestrator && ruff check

Auto-Fixing

# Show what would be fixed (diff preview)
ruff check --diff

# Apply safe automatic fixes
ruff check --fix

# Fix specific files
ruff check --fix src/main.py

# Fix with preview (see changes before applying)
ruff check --diff services/orchestrator
ruff check --fix services/orchestrator

Output Formats

# Default output
ruff check

# Show statistics
ruff check --statistics

# JSON output for tooling
ruff check --output-format json

# GitHub Actions annotations
ruff check --output-format github

# GitLab Code Quality report
ruff check --output-format gitlab

# Concise output
ruff check --output-format concise

Rule Selection

Common Rule Codes

CodeDescriptionExample Rules
Epycodestyle errorsE501 (line too long)
FPyflakesF401 (unused import)
Wpycodestyle warningsW605 (invalid escape)
Bflake8-bugbearB006 (mutable default)
IisortI001 (unsorted imports)
UPpyupgradeUP006 (deprecated types)
SIMflake8-simplifySIM102 (nested if)
DpydocstyleD100 (missing docstring)
Npep8-namingN806 (variable naming)
Sflake8-bandit (security)S101 (assert usage)
C4flake8-comprehensionsC400 (unnecessary generator)

Selecting Rules

# Select specific rules at runtime
ruff check --select E,F,B,I

# Extend default selection
ruff check --extend-select UP,SIM

# Ignore specific rules
ruff check --ignore E501,E402

# Show which rules would apply
ruff rule --all

# Explain a specific rule
ruff rule F401

Rule Queries

# List all available rules
ruff rule --all

# Search for rules by pattern
ruff rule --all | grep "import"

# Get detailed rule explanation
ruff rule F401
# Output: unused-import (F401)
#   Derived from the Pyflakes linter.
#   Checks for unused imports.

# List all linters
ruff linter

# JSON output for automation
ruff rule F401 --output-format json

Configuration

pyproject.toml

[tool.ruff]
# Line length limit (same as Black)
line-length = 88

# Target Python version
target-version = "py311"

# Exclude directories
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

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

# Disable specific rules
ignore = [
    "E501",  # Line too long (handled by formatter)
    "B008",  # Function calls in argument defaults
]

# Allow automatic fixes
fixable = ["ALL"]
unfixable = ["B"]  # Don't auto-fix bugbear rules

# Per-file ignores
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"tests/**/*.py" = ["S101"]  # Allow assert in tests

ruff.toml (standalone)

# Same options as pyproject.toml but without [tool.ruff] prefix
line-length = 100
target-version = "py39"

[lint]
select = ["E", "F", "B"]
ignore = ["E501"]

[lint.isort]
known-first-party = ["myapp"]
force-single-line = true

Advanced Usage

Per-file config overrides, targeted rule checks, and changed-files-only / parallel invocation patterns are in references/command-recipes.md.

CI/CD Integration

Quick form — lint with PR annotations on GitHub Actions:

# .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'

Quick form — pre-commit hook:

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

For the full integration recipes — editor setup (VS Code, Neovim, Zed, Helix), the advanced pre-commit config, GitLab/CircleCI/Jenkins, Make/Just/Task/tox, Docker, LSP server settings, and Flake8/Black/pylint migration guides — see REFERENCE.md.

Common Patterns

Recipes for finding specific issues, gradual adoption, and refactoring support are in references/command-recipes.md.

Plugin Configuration

Per-plugin [tool.ruff.lint.<plugin>] settings (isort, flake8-quotes, pydocstyle, pylint) are in references/plugin-configuration.md.

Best Practices

When to Use ruff check

  • Code quality enforcement
  • Pre-commit validation
  • CI/CD pipelines
  • Refactoring assistance
  • Security scanning
  • Import organization

Critical: Directory Parameters

  • ✅ Always pass directory as parameter: ruff check services/orchestrator
  • ❌ Never use cd: cd services/orchestrator && ruff check
  • Reason: Parallel execution, clearer output, tool compatibility

Rule Selection Strategy

  1. Start minimal: select = ["E", "F"] (errors + pyflakes)
  2. Add bugbear: select = ["E", "F", "B"]
  3. Add imports: select = ["E", "F", "B", "I"]
  4. Add pyupgrade: select = ["E", "F", "B", "I", "UP"]
  5. Consider security: select = ["E", "F", "B", "I", "UP", "S"]

Fixable vs Unfixable

  • Mark uncertain rules as unfixable to review manually
  • Common unfixables: B (bugbear), F (pyflakes F401)
  • Let ruff fix safe rules: I (isort), UP (pyupgrade)

Common Mistakes to Avoid

  • Using cd instead of passing directory parameter
  • Enabling ALL rules immediately (use gradual adoption)
  • Not using --diff before --fix
  • Ignoring rule explanations (ruff rule <code>)
  • Not configuring per-file ignores for special cases

Quick Reference

Essential Commands

# Basic operations
ruff check                          # Lint current directory
ruff check path/to/dir              # Lint specific directory
ruff check --diff                   # Show fix preview
ruff check --fix                    # Apply fixes

# Rule management
ruff rule --all                     # List all rules
ruff rule F401                      # Explain rule F401
ruff linter                         # List all linters

# Output formats
ruff check --statistics             # Show violation counts
ruff check --output-format json     # JSON output
ruff check --output-format github   # GitHub Actions format

# Selection
ruff check --select E,F,B          # Select rules
ruff check --ignore E501           # Ignore rules
ruff check --extend-select UP      # Extend selection

Configuration Hierarchy

  1. Command-line arguments (highest priority)
  2. ruff.toml in current directory
  3. pyproject.toml in current directory
  4. Parent directory configs (recursive)
  5. User config: ~/.config/ruff/ruff.toml

Common Rule Combinations

# Minimal safety
ruff check --select E,F

# Good default
ruff check --select E,F,B,I

# Comprehensive
ruff check --select E,F,B,I,UP,SIM

# Security-focused
ruff check --select E,F,B,S

# Docstring enforcement
ruff check --select D --config '[lint.pydocstyle]\nconvention = "google"'

This makes ruff check the preferred tool for fast, comprehensive Python code linting.

FAQ

What does the ruff-linting skill do?

Python linting with ruff. Fast linting, rule selection, auto-fixing, and config. Use when checking Python code quality, enforcing standards, or finding bugs.

How do I install ruff-linting?

Run npx skills add https://github.com/laurigates/claude-plugins --skill ruff-linting in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ruff-linting/ (personal) or .claude/skills/ruff-linting/ (project).

Which AI agents can use ruff-linting?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is ruff-linting safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains ruff-linting?

It is published by laurigates in laurigates/claude-plugins. It has 466 recorded installs.

More from laurigates/claude-plugins

View all →

python-code-quality

laurigates/claude-plugins

Python code quality with ruff and ty. Use when the user mentions ruff, ty, linting, formatting, type checking, or Python code style.

1K installs

python-testing

laurigates/claude-plugins

Python testing with pytest, coverage, fixtures, and mocking. Use when the user mentions pytest, unit tests, coverage, fixtures, mocking, or writing Python tests.

Testing & QA428 installs

pytest-advanced

laurigates/claude-plugins

Advanced pytest: fixtures, markers, parametrization, parallel execution. Use when implementing test infrastructure, writing fixtures, or running with coverage.

Testing & QA352 installs

uv-workspaces

laurigates/claude-plugins

Manage multi-package Python projects with uv workspaces. Use when the user mentions uv workspaces, Python monorepo, shared lockfiles, or member dependencies.

321 installs

basedpyright-type-checking

laurigates/claude-plugins

Open the skill to read its SKILL.md instructions.

320 installs

uv-project-management

laurigates/claude-plugins

Python project setup, deps, and lockfiles with uv. Use when the user mentions uv, creating Python projects, managing dependencies, lockfiles, or pyproject.toml.

320 installs

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs