Automatically triggered when setting up Python code quality tooling, configuring linters, adding type checking, improving code standards, running code quality checks, setting up pre-commit hooks, or auditing Python code for quality issues. Applies when discussing: ruff setup, mypy configuration, code formatting, linting rules, cyclomatic complexity, dead code detection, file length limits, pre-commit hooks, Makefile targets for quality, uv-based workflows, pyproject.toml configuration, or "check my code quality". Also triggers on: "set up linting", "add type checking", "configure ruff", "format my code", "run quality checks", "set up pre-commit", "code smells", "clean up this code", "add code quality", "quality gate", "CI quality pipeline".
Python Code Quality Skill
This skill sets up and enforces comprehensive Python code quality using a battle-tested
toolchain. Based on real production Makefiles using uv for fast dependency management.
Philosophy
Fast feedback: Use uv run and uvx for instant tool execution — no global installs
Layered checks: Lint → Format → Typecheck → Complexity → Dead Code → File Length
CI-ready: Every check is a Makefile target that returns non-zero on failure
Opinionated defaults: Start strict, relax only with justification
Tools that run via uvx (no install needed): xenon, vulture.
Setup: Makefile Targets
Add these targets to the project Makefile:
# =============================================================================# Code Quality# =============================================================================lint:
uv run ruff check src tests
lint-fix:
uv run ruff check --fix src tests
format:
uv run ruff format src tests
format-check:
uv run ruff format --check src tests
typecheck:
uv run mypy src/PROJECT_NAME
# File length gate (max 500 lines per .py file)
MAX_LINES := 500
file-length:
@FAILED=0; \
for f in $$(find src/ -name '*.py'); do \
count=$$(wc -l < "$$f"); \
if [ "$$count" -gt $(MAX_LINES) ]; then \
echo "ERROR: $$f has $$count lines (max $(MAX_LINES))"; \
FAILED=1; \
fi; \
done; \
if [ "$$FAILED" -eq 1 ]; then \
echo ""; \
echo "Files exceeding $(MAX_LINES) lines must be split into smaller modules."; \
exit 1; \
fi; \
echo "All files under $(MAX_LINES) lines."# Cyclomatic complexity gate (Xenon grade C)complexity:
cd /tmp && uvx xenon --max-absolute C --max-modules D --max-average C $(CURDIR)/src/
# Dead code detectiondead-code:
uvx vulture src/ --min-confidence 90
# Ensure dev dependencies are installedensure-dev:
@uv sync --all-extras --quiet
# Run all checks (same as CI)check: ensure-dev lint format-check typecheck file-length complexity test
@echo "All checks passed!"# Full CI-equivalent pipeline (locally)ci: ensure-dev lint format-check typecheck file-length complexity dead-code test
@echo "Full CI pipeline passed!"
Setup: Pre-commit Hooks
Create .pre-commit-config.yaml:
repos:-repo:https://github.com/astral-sh/ruff-pre-commitrev:v0.8.6# Pin to a specific versionhooks:-id:ruffargs: [--fix]
-id:ruff-format-repo:https://github.com/pre-commit/mirrors-mypyrev:v1.13.0hooks:-id:mypyadditional_dependencies: [] # Add stubs your project needs-repo:https://github.com/pre-commit/pre-commit-hooksrev:v5.0.0hooks:-id:trailing-whitespace-id:end-of-file-fixer-id:check-yaml-id:check-added-large-filesargs: ['--maxkb=500']
-id:check-merge-conflict-id:debug-statements
Install hooks:
uv run pre-commit install
Running Checks
Quick Check (During Development)
make lint format-check typecheck
Full Quality Gate (Before Committing)
make check
This runs: lint → format-check → typecheck → file-length → complexity → test
Full CI Pipeline (Before Pushing)
make ci
Adds: dead-code to the check pipeline.
When Reviewing Existing Code
When asked to review or improve code quality in an existing project, follow this order:
1. Assess Current State
# Check if quality tools are configuredcat pyproject.toml | grep -A5 'tool.ruff'cat pyproject.toml | grep -A5 'tool.mypy'ls .pre-commit-config.yaml
ls Makefile
2. Run Existing Checks (If Available)
make lint 2>/dev/null || uv run ruff check src/
make typecheck 2>/dev/null || uv run mypy src/
3. Report Findings
Structure findings as:
Critical: Type errors, undefined names, security issues (ruff S rules)
