python-linting

Python Linting Skill

Run this skill when asked to lint, format, check style, or check types for Python code.

Step 1 — Detect available tooling

Check which linting/formatting tools are configured or installed, in order of preference:

# Config files (indicate which tool the project already uses)
ls pyproject.toml setup.cfg .flake8 mypy.ini 2>/dev/null

# Installed tools
which ruff black flake8 mypy isort 2>/dev/null

Prefer ruff if configured or installed — it replaces flake8, isort, and much of pylint with a single fast tool. Fall back to flake8 + black + isort if ruff is not available. Do not install new tools without asking the user first.

---

Step 2 — Run linting (read-only check)

# Preferred
ruff check .

# Fallback
flake8 .

Report all findings grouped by file, with line numbers and rule codes.

---

Step 3 — Run formatting check

# Preferred
ruff format --check --diff .

# Fallback
black --check --diff .
isort --check-only --diff .

Show the proposed diff to the user before applying any formatting changes.

---

Step 4 — Run type checking (if type hints are used)

mypy .

Skip this step if the project has no type hints and no mypy configuration.

---

Step 5 — Apply fixes (only with user confirmation)

# Preferred
ruff check --fix .
ruff format .

# Fallback
black .
isort .

Only run auto-fix commands after showing the user what will change and getting explicit confirmation. Never auto-fix mypy type errors — these require manual code changes.

---

Standard conventions enforced

• Line length: 88 (black/ruff default) or 79 (PEP 8 strict) — follow whatever the project's config specifies; do not override it.
• Import order: standard library, then third-party, then local — grouped and alphabetized (isort/ruff default).
• Naming: snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE_CASE for constants (PEP 8).
• No unused imports or variables.
• No bare except: clauses — always catch specific exceptions.