version: "1.0.0" name: python-lint description: Sets up and tunes Ruff linting and formatting for a Python package — pyproject [tool.ruff] rule selection, Black/Flake8/isort migration — and fixes lint or format failures. Use when the user says 'set up linting', 'add ruff', 'fix lint errors', 'configure the formatter'. Not for type errors, non-Python file formatting, pre-commit wiring, or CI workflows. license: MIT

python-lint

Purpose

Configure Ruff as the single linter and formatter for a Python package — replacing Black, Flake8 (+ plugins), isort, and pyupgrade — with an explicit rule set in pyproject.toml, then drive ruff check and ruff format --check to a clean exit. Covers fresh setup, migration from the legacy stack, rule tuning, and fixing lint or format failures. Every command below runs in the user's package repository.

When NOT to use

• Type errors / mypy / pyright / ty — Ruff performs no type inference; ANN

rules only police annotation style. The python-typing skill, if installed, owns this.

• Pre-commit wiring (.pre-commit-config.yaml, hook rev pinning, staged-file

runs) — the python-precommit skill. This skill only defines what Ruff should do.

• CI workflow YAML (GitHub Actions jobs, matrices, caching) — the python-ci

skill. This skill supplies the commands a CI job should run, not the workflow.

• Formatting YAML / JSON / TOML / Markdown prose — Ruff formats Python

(including, since 0.16, Python code fences inside Markdown) and nothing else, by deliberate maintainer decision (astral-sh/ruff#10738); the python-precommit skill covers non-Python files.

• Running Ruff automatically on agent edits (Claude Code hooks) — the

agent-guardrails skill.

Workflow

1. Inspect before touching anything

ls .flake8 .isort.cfg setup.cfg tox.ini ruff.toml .ruff.toml 2>/dev/null
grep -nE '^\[tool\.(ruff|black|isort)|^\[flake8\]|^\[isort\]' pyproject.toml setup.cfg tox.ini 2>/dev/null
grep -n 'requires-python' pyproject.toml

Pick the path: fresh setup (steps 2–3), migration off Black/Flake8/isort (step 5), tuning an existing config (step 4), or fixing a red lint gate (step 6).

2. Install a pinned Ruff

uv add --dev "ruff==0.16.6"        # example pin — check the latest release and pin that
# one-off, no project change:
uvx --from 'ruff==0.16.6' ruff check .

No-uv fallback (once, applies to every command below): python -m pip install 'ruff==0.16.6' and drop the uv run prefix.

Why pin — formatter output and the rule catalog change between minor releases: 0.15 shipped a "2026 style guide" that changed lambda and empty-line formatting (astral.sh/blog/ruff-v0.15.0), and 0.16 (2026-07-23) grew the default rule set from 59 to 413 rules while dropping 18 E/F codes from it, so an unconfigured repo's findings changed overnight (astral.sh/blog/ruff-v0.16.0). An unpinned Ruff makes local, teammate, and CI runs disagree — the top reported lint-workflow failure. Optionally enforce the pin in config with required-version = "0.16.6" under [tool.ruff]. Note that uv format (experimental since uv 0.8.13) runs a Ruff it bundles itself, so its version can differ from the project's pin — keep ruff in dev dependencies as the source of truth and treat uv format as a convenience wrapper.

3. Write the config (fresh setup)

All Ruff config lives in pyproject.toml. Keep exactly one config file — a ruff.toml next to a [tool.ruff] section is a recipe for confusion. Starter:

[tool.ruff]
target-version = "py311"          # lowest Python you support; gates UP rewrites
line-length = 88
extend-exclude = ["migrations"]   # generated code, if any
 
[tool.ruff.lint]
select = [
    "E", "W",   # pycodestyle
    "F",        # pyflakes
    "I",        # isort (import sorting)
    "UP",       # pyupgrade
    "B",        # flake8-bugbear
    "C4",       # flake8-comprehensions
    "SIM",      # flake8-simplify
    "RUF",      # Ruff-specific rules
]
ignore = ["E501"]                 # line length is the formatter's job
 
[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]        # assert is fine in tests (relevant once S is on)
"__init__.py" = ["F401"]          # re-exports
 
[tool.ruff.lint.isort]
known-first-party = ["yourpackage"]
 
[tool.ruff.format]
quote-style = "double"
docstring-code-format = true      # formats Python snippets inside docstrings

Non-obvious decisions baked into this block:

• Never rely on Ruff's default rule set. Before 0.16 it was E4/E7/E9
• F (59 rules, less than a Flake8+plugins stack); since 0.16 it is 413 rules across

B, UP, SIM, PL and more, with 18 former E/F defaults removed — a repo without select gets a different gate on every upgrade. select replaces the default set, so an explicit list freezes it; select = ["E4", "E7", "E9", "F"] reproduces the pre-0.16 baseline if a team wants exactly that.

• `ignore = ["E501"]` whenever the formatter is enabled — ruff format already

wraps at line-length; linting it too double-reports on lines the formatter cannot break (URLs, long strings).

• `target-version` gates `UP` (pyupgrade) rewrites. If unset, Ruff falls back

to project.requires-python; if that is also absent it assumes py310, and autofixes can emit syntax that crashes older supported runtimes.

• Avoid select = ["ALL"] — it silently enables every new rule on every Ruff

upgrade, breaking checks unpredictably. Official guidance is to start narrow and grow one category at a time (docs.astral.sh/ruff/linter/).

Deeper rule catalog, tier strategy, and sub-table options (isort, pydocstyle, bugbear): references/rule-selection.md.

4. Tune an existing config

• Noise in one area (tests, scripts, notebooks) → scope it with

[tool.ruff.lint.per-file-ignores]; never delete the rule from select globally because tests complain. Common: "tests/**/*.py" = ["S101", "PLR2004"], "scripts/*" = ["T201"].

• A single intentional violation → # noqa: <CODE> with the specific code and a

short reason. Bare # noqa hides every rule on the line.

• Codes from non-Ruff tools in # noqa comments (custom Flake8 plugin) →

declare external = ["XX"] in [tool.ruff.lint], or RUF100 strips those comments on the next --fix.

• Widen coverage one prefix at a time ("S", "PT", "PTH", …), run

uv run ruff check . after each addition, and fix or scope before adding more.

• Sanity-check the result: python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .

(read-only; flags E501 double-reporting, ALL, formatter-conflicting rules, leftover legacy configs, missing target-version).

5. Migrate from Black / Flake8 / isort

Full mapping tables (commands, config keys, Flake8-plugin→prefix) and the large-legacy-codebase strategy: references/migration.md. The sequence:

1. Translate config first. [tool.black] → [tool.ruff] + [tool.ruff.format],

[tool.isort]/.isort.cfg → [tool.ruff.lint.isort] (kebab-case keys), .flake8 → select/ignore/per-file-ignores. Ruff never reads [tool.black] or .flake8 — anything not translated is silently lost.

1. Check plugin parity. For each Flake8 plugin in use, confirm a Ruff prefix

exists (table in the reference). A business-critical plugin with no equivalent → hybrid: keep Flake8 scoped to that plugin, add its codes to external = [...].

1. One-time cleanup as its own reviewed commit, before any gate is switched:

``bash uv run ruff check . --fix && uv run ruff format . ` Review the diff — Ruff's formatter is close to Black on large codebases but not byte-identical; deviations are documented at [docs.astral.sh/ruff/formatter/black/](https://docs.astral.sh/ruff/formatter/black/). For a large reformat, record the commit in .git-blame-ignore-revs`.

1. Retire the old stack in the same PR: remove black/flake8/isort (and their

plugins) from dev dependencies; delete .flake8, .isort.cfg, [tool.black], [tool.isort]. Two active formatters will fight over the same lines (astral-sh/ruff#1307).

1. Tell the user to repoint whatever invoked the old tools — pre-commit hooks

(python-precommit skill) and CI jobs (python-ci skill). Provide only the commands: ruff check . and ruff format --check ..

An existing Black+Flake8 setup that works and hurts nobody is a valid reason to not migrate — churn has cost. Migrate when there is friction (speed, config sprawl, plugin abandonment), not for fashion.

6. Fix lint / format failures

uv run ruff check . --fix    # 1. autofix what's safe
uv run ruff format .         # 2. THEN format — fixes can leave code needing reformat
uv run ruff check .          # 3. see what's left; --fix exiting clean != zero violations

Order matters: --fix rewrites imports/comprehensions that then need reformatting. For what remains:

• Fix the code. Reach for suppressions only when the violation is intentional, and

then the narrowest one: specific # noqa: <CODE> > per-file-ignores > global ignore. Never make a red gate green by deleting rules from select.

• Some fixes are deliberately held back as unsafe (could change behavior). Review

them explicitly with uv run ruff check . --fix --unsafe-fixes --diff before applying.

• In GitHub Actions logs, uv run ruff check . --output-format=github emits

file/line annotations on the PR (the workflow YAML itself is python-ci territory).

7. Verify done

uv run ruff check . && uv run ruff format --check . && echo LINT-OK
python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .

Output spec

Done means all of:

• pyproject.toml has [tool.ruff] with an explicit select, E501 ignored

while the formatter is in use, and a resolved target-version (or requires-python).

• Ruff pinned in dev dependencies (and optionally required-version in config).
• uv run ruff check . and uv run ruff format --check . both exit 0.
• No leftover .flake8 / .isort.cfg / [tool.black] / [tool.isort], and no

black/flake8/isort in dev dependencies (unless the documented hybrid pattern).

• Migrations: the mechanical reformat isolated in its own commit; suppressions

carry rule codes and reasons.

• scripts/check_ruff_config.py reports 0 errors.

Failure modes & gotchas

Bundled resources

• references/rule-selection.md — rule-prefix→origin map, tiered adoption

strategy, select vs extend-select vs ALL trade-offs, per-file-ignore conventions, isort/pydocstyle/bugbear sub-tables, fix-safety knobs.

• references/migration.md — old-command→Ruff mapping, Black/isort/Flake8 config

key translation, Flake8-plugin→prefix table, custom-plugin hybrid, incremental adoption for large legacy codebases.

• scripts/check_ruff_config.py — read-only config sanity checker; exits non-zero

on findings. Run python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root <repo> (--strict to fail on warnings too).