python-lint

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 only, 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.15.6"        # example pin — check the latest release and pin that
# one-off, no project change:
uvx --from 'ruff==0.15.6' ruff check .

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

Why pin — formatter output and the rule catalog change between minor releases (the 0.15 release shipped a "2026 style guide" that changed lambda and empty-line formatting; see astral.sh/blog/ruff-v0.15.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.15.6" under [tool.ruff]. Note that uv format (uv 0.10.0+) runs Ruff's formatter under the hood — the same pinning logic applies.

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:

• Ruff's out-of-the-box rule set is only E + F. A team that "installed Ruff" without select gets far less coverage than its old Flake8+plugins stack. Always write an explicit select.
• 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.
2. 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 = [...].
3. One-time cleanup as its own reviewed commit, before any gate is switched:

   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/. For a large reformat, record the commit in .git-blame-ignore-revs.
4. 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).
5. 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

Symptom	Cause	Fix
Ruff installed but misses obvious problems	Default rules are only E+F	Write an explicit select (step 3)
E501 violations the formatter refuses to fix	Linter and formatter both own line length	ignore = ["E501"]; the formatter wraps what it can
Routine Ruff upgrade suddenly fails checks	select = ["ALL"] auto-enables new rules	Explicit select; pin the Ruff version
Formatter and linter fight (commas, quotes, string concat)	COM812, ISC001, Q rules conflict with ruff format	Drop them from select/add to ignore — see conflicting rules
--fix deletes # noqa: XY123 comments	RUF100 treats unknown codes as unused suppressions	external = ["XY"] in [tool.ruff.lint]
Autofix emits syntax that breaks the oldest supported Python	No target-version / requires-python → py310 assumed	Set target-version to the real minimum
Excluded files still linted when paths are passed one-by-one	Explicit file args bypass exclude (ruff#9585)	Use per-file-ignores for must-hold rules; hook-layer wiring belongs to python-precommit
ruff check --fix exits clean, CI still red	Only safe fixes auto-apply; the rest still report	Re-run plain check; fix manually or review --unsafe-fixes --diff
Files keep flip-flopping between formats	Black (or an IDE Black plugin) still active alongside Ruff	One formatter only — remove Black, update editor settings
Old .flake8 / [tool.black] settings "stopped working"	Ruff never reads them	Translate into [tool.ruff], then delete the originals
Passes locally, fails elsewhere	Version drift across dev/CI/hooks	Same pinned version everywhere; required-version makes mismatch a hard error
Expected Ruff to format YAML/Markdown/TOML	Python-only by design; Markdown code blocks are preview-only (--preview + extend-include)	python-precommit skill covers non-Python formatting
First CI run after adding Ruff fails hard	No local cleanup pass before wiring the gate	Run step 6 locally, commit, then gate
ruff check green but diffs look unformatted	Lint and format are separate concerns — check doesn't verify formatting	Always run both gates (step 7)

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