Modern Python

Ruff is the rule database and the project's target Python version is the gate. The bundled tool lists only the modernization rules whose own Ruff examples diagnose under that target, so nobody curates a rule table and the guidance tracks Ruff. It corrects two things at once: training-data lag (a feature newer than the model) and frequency bias (the older pattern the model reaches for out of habit).

Tool: python <skill-dir>/scripts/modern_python.py, where <skill-dir> is this folder. Subcommands: list, explain, check, fix, probe.

Step 0: the project's answers

Read .claude/modern-python.md at the repo root. It holds the interview answers: codebase, convention, enforcement, target, target-source, ruff-fallback, profile.

• Present: continue with its values.
• Absent: run the interview in references/interview.md once, write the file, continue. If the user declines the interview, proceed with enforcement: advisory, convention: preserve, no target override, say so once, and do not ask again this session.
• The repo's CLAUDE.md carries modern-python: off: proceed as declined without asking. That is the line for a repo whose .claude/ is not yours to write (onboard-light territory).
• /modern-python setup re-runs the interview and rewrites the file.

Before editing Python

1. List the guidance that applies to the file you are about to touch:

   python <skill-dir>/scripts/modern_python.py list --file path/to/file.py --target-version <target> --profile <profile>

   Omit --target-version when target-source: declared. For a file that does not exist yet, pass --target-version from the answers file.

2. Exit 3 means the project's Ruff is too old to report rule metadata. Ask whether to update Ruff through the project's own manager (uv, Poetry, PDM, pre-commit). On yes, update and rerun. On no, rerun with --allow-stale and rely on the post-edit check.
3. Read the complete output. Do not pipe it through head, tail, grep, sed, or any other truncating or filtering command: a rule dropped there is a rule you will violate. Baseline rules diagnose under the target now; conditional ones need from __future__ import annotations.

4. For every listed rule that may touch the code you plan to write, read its explanation before editing:

   python <skill-dir>/scripts/modern_python.py explain --file path/to/file.py UP045 FURB123

   Skipping a relevant rule costs the same call: explain it first, then skip with the reason stated.

5. Apply the convention the answers file sets:
   • convention: override: follow a returned rule even when nearby code or repository convention uses the older pattern. Four exits only: it would not run on the target, it would change behaviour, it clearly does not match the edited code, or a fix-scoped skill is active (surgical-patch, a cavecrew builder), in which case rules apply only to the lines the fix already touches.
   • convention: preserve: inside existing files, match the surrounding pattern. Use the modern idiom in new files and new functions, and everywhere when the task is a modernization pass.
6. Write the code. The target version is the compatibility boundary: no syntax or stdlib API newer than it. When the tool reports Ruff default (no project configuration found) and the answers file carries no target, the target is unknown: avoid version-gated syntax and say so.

After editing Python

enforcement: advisory: done after the edit. Report which rules you applied.

enforcement: verified or enforced:

1. Check the files you touched (exit 1 means findings remain). Add --target-version <target> when the answers file says target-source: chosen, since Ruff otherwise checks at its own default; --concise prints one line per finding instead of JSON:

   python <skill-dir>/scripts/modern_python.py check --concise path/to/file.py

2. explain each finding you do not already understand. Fix by hand, or apply Ruff's safe fixes with the same flags:

   python <skill-dir>/scripts/modern_python.py fix --concise path/to/file.py

3. check again until it exits 0, or name the remaining findings and the documented caveat that applies to each.
4. Run the project's own formatter, type checker and tests for the changed code. This check supplements them.

enforced additionally means a PostToolUse hook runs the same check on every edited .py file and returns findings as context. That hook is installed only by onboard-repo Phase 4b, with its HARNESS.md entry and a tested fire case; this skill never writes settings.json. Asked for enforcement outside onboarding: say to run onboard-repo and re-run Phase 4b alone.

Profiles

core is UP, FURB, F401. modern (default) adds SIM, C4, PIE, PTH, FLY, PERF. Preview rules stay off unless the project opts in.

Done when

The listed rules were read in full, every relevant one was applied or explained away, the edit respects the target, and under verified or enforced the check exits 0 or the remaining findings are named with their caveat.