python-bootstrap

name	python-bootstrap
description	Use whenever a Python project needs scaffolding or retrofitting to the arsenal defaults — uv, ruff, strict mypy, the standard Makefile, a 3.12+ floor — reports the missing pieces and applies them. Triggers — "set up a Python project", "add ruff and mypy config". Do NOT use to publish to PyPI (see pypi-release) or to upgrade dependencies (see dep-upgrade).
argument-hint	[project_dir]
metadata	{"type":"capability"}
user-invocable	true

python-bootstrap

Bring a Python project in line with the arsenal defaults — uv, ruff, strict mypy, the standard Makefile, requires-python>=3.12 — whether scaffolding from scratch or retrofitting an existing repo.

CANARY: python-bootstrap-loaded-2026-06-04-ea39c2b5-394e8afa1019319d

When to load

Load when a Python repo needs its tooling created or brought up to standard: a fresh project with no pyproject.toml, or an existing one missing the ruff select list, the strict mypy block, or the Makefile targets.

If the request is to publish a package, defer to the pypi-release skill; if it is to upgrade dependencies, defer to dep-upgrade.

Step 1 — Report the gaps

Run from the target project root (the script reads the current directory by default, like the other arsenal analysis skills):

python3 "${CLAUDE_SKILL_DIR}/scripts/analyze_project.py" [project_dir]

It emits a JSON report: mode (scaffold if no pyproject.toml, else retrofit), per-tool present/missing detail (ruff.missing_select, mypy.missing_keys, makefile.missing_targets), requires_python_ok, and model_gen (whether a models/*.json spec dir exists).

Step 2 — Apply the canonical blocks

Open references/canonical-config.md and apply only what the report flags as missing. Merge into existing tables — never overwrite a populated [tool.ruff] or [tool.mypy] wholesale; a project may carry its own per-file-ignores or module overrides worth keeping. Match every version string (target-version, python_version, requires-python) to what the project actually supports.

After editing, run the project's own make lint / make test (or the raw uv run ruff check . / uv run mypy .) to confirm the new config is clean.

Step 3 — Hand off a model spec, don't duplicate it

If model_gen.specs_present is true, the project drives a JSON-spec backend generator. Scaffolding SQLAlchemy models, Pydantic schemas, or FastAPI routes by hand is out of scope — hand off to the model-generator toolkit (model-gen / model-val), which owns that layer. This skill only sets up repo tooling.

References — load on demand

• Canonical config — load in Step 2; the verbatim pyproject (ruff + mypy), Makefile, and uv blocks to apply.

Gotchas

• Retrofit clobbers project-specific config. Pasting the canonical [tool.ruff] over an existing one silently drops a project's per-file-ignores or extra select codes. Read the current table first and merge — add the missing pieces, keep the rest.
• The flags are defaults; the version strings are not. Copying target-version = "py312" / requires-python = ">=3.12" into a repo that supports 3.9 breaks installs and mis-lints. Always reconcile the versions with what the project ships.
• black and ruff format fight. If black is configured, retrofitting ruff format without removing black causes format thrash on every commit. Drop black as part of the change.
• Strict mypy floods a legacy codebase. Turning on the strict block over an untyped repo can surface thousands of errors at once. Apply per-module [[tool.mypy.overrides]] to stage adoption rather than weakening the global block.
• Running from the arsenal repo, not the target. The script reads the current directory; launched from this marketplace checkout it reports the marketplace's gaps, not the project's. cd to the target project first.