bootstrap-python

A Claude Code skill that scaffolds a production-ready Python project with a single command.

Instead of spending 30 minutes wiring up Docker, Postgres, migrations, linting, and folder structure every time you start a new project, run /bp and get straight to building.

Usage

/bp

Or describe what you want naturally:

"set up a new python API project with postgres"
"bootstrap a python project in this folder"
"new python backend"

What It Creates

your-project/
├── .venv/                  Python virtual environment
├── .git/                   Initialized git repository
├── docker-compose.yml      PostgreSQL + pgAdmin services
├── .gitignore              Python-tuned ignores
├── .env                    Local dev environment variables
├── .env.example            Template for collaborators
├── requirements.txt        Python dependencies (installed)
├── pyproject.toml          Project metadata + tool config
├── Makefile                Common commands
├── alembic.ini             Migration config
├── alembic/
│   ├── env.py              Configured to read DATABASE_URL from .env
│   ├── script.py.mako      Migration file template
│   └── versions/           Where migration files live
├── src/
│   ├── __init__.py
│   ├── main.py             FastAPI app with health check
│   └── config.py           Pydantic settings loader
└── tests/
    ├── __init__.py
    └── conftest.py          Pytest fixtures placeholder

Why Each Piece Exists

docker-compose.yml

Runs two services:

• PostgreSQL via pgvector/pgvector:pg16 — standard Postgres with the pgvector extension pre-installed. pgvector adds vector similarity search, which is increasingly essential for AI/ML features like semantic search, RAG, and embeddings. Even if you don't need it on day one, it's there when you do — and it costs nothing to have it available.
• pgAdmin via dpage/pgadmin4 — a web UI for inspecting your database at http://localhost:5050. Useful for debugging queries, checking schema, and browsing data without writing SQL in a terminal.

Postgres includes a health check so dependent services (like pgAdmin) wait until the database is actually ready before starting. Data persists in a named volume (pgdata) so you don't lose everything when you restart containers.

.env / .env.example

.env holds your local configuration — database credentials, service URLs, API keys. It's excluded from git via .gitignore so secrets never get committed.

.env.example is the committed template. When a collaborator clones the repo, they copy it to .env and fill in their own values. This pattern keeps secrets out of version control while making setup self-documenting.

Default values use postgres/postgres for local dev — simple and disposable.

.gitignore

Covers the things that should never be committed in a Python project:

• .venv/ — virtual environments are machine-specific and large
• __pycache__/, *.pyc — compiled bytecode, regenerated automatically
• .env — secrets and local config
• .pytest_cache/, .coverage, htmlcov/ — test artifacts
• .mypy_cache/ — type checker cache
• dist/, build/, *.egg-info/ — packaging artifacts
• .vscode/, .idea/ — editor config (personal preference, not project config)

requirements.txt

Grouped by purpose:

Package	Why
psycopg2-binary	PostgreSQL adapter for Python. The -binary variant includes pre-compiled C extensions so you don't need libpq-dev installed.
sqlalchemy	SQL toolkit and ORM. Lets you define models as Python classes and query without raw SQL.
alembic	Database migration tool built on SQLAlchemy. Tracks schema changes over time so deployments are repeatable.
pgvector	Python bindings for the pgvector Postgres extension. Adds vector column types and similarity search to SQLAlchemy models.
fastapi	Modern async web framework. Auto-generates OpenAPI docs, handles validation, and is one of the fastest Python frameworks.
uvicorn[standard]	ASGI server that runs FastAPI. The [standard] extra includes uvloop and httptools for better performance.
python-dotenv	Loads .env files into environment variables. Used by alembic and can be used anywhere you need config.
pydantic	Data validation using Python type hints. FastAPI uses it for request/response models.
pydantic-settings	Extension for loading settings from environment variables and .env files with type validation.
pytest	Testing framework. Simple, powerful, and the de facto standard for Python.
httpx	Async HTTP client. Used for testing FastAPI endpoints with TestClient.
ruff	Linter and formatter. Replaces flake8, isort, and black in a single tool that runs in milliseconds.

pyproject.toml

The modern standard for Python project metadata (PEP 621). Replaces the old setup.py / setup.cfg approach. Also configures:

• Ruff — 120 char line length, targeting Python 3.11+, with a sensible set of lint rules (errors, warnings, import sorting, naming, upgrades)
• Pytest — looks for tests in tests/, adds the project root to pythonpath so imports work without installing the package

src/main.py

A minimal FastAPI application with two endpoints:

• GET / — returns {"status": "ok"}, a simple proof of life
• GET /health — returns {"status": "healthy"}, useful for Docker health checks and load balancer probes

This exists so make dev works immediately. You can start the server, hit an endpoint, and confirm the stack is wired up before writing any real code.

src/config.py

Uses pydantic-settings to load configuration from .env with type validation. Provides a single settings object you import anywhere:

from src.config import settings
print(settings.database_url)

Adding a new setting is just adding a field to the class — pydantic handles parsing, defaults, and validation.

alembic/

Database migration tooling. Alembic tracks your schema changes as versioned Python scripts so you can:

• Apply migrations to any database with make migrate
• Auto-generate migrations from model changes with make migration msg="add users table"
• Roll back changes when needed

The env.py is pre-configured to read DATABASE_URL from your .env file instead of hardcoding it in alembic.ini.

Makefile

Wraps common commands so you don't have to remember exact syntax:

Command	What it does
make up	Start PostgreSQL and pgAdmin in the background
make down	Stop all containers
make db	Open a psql shell connected to your database
make migrate	Apply all pending database migrations
make migration msg="description"	Auto-generate a new migration from model changes
make install	Install Python dependencies from requirements.txt
make test	Run the test suite
make dev	Start the FastAPI dev server with auto-reload on port 8000
make lint	Lint and auto-format code with ruff

.venv/

A Python virtual environment created in the project directory. Keeps your project's dependencies isolated from your system Python and other projects. The skill creates it and installs all dependencies into it automatically.

Quick Start After Bootstrapping

make up          # Start Postgres + pgAdmin
make dev         # Start FastAPI dev server

# Visit:
#   http://localhost:8000       API
#   http://localhost:8000/docs  Swagger UI
#   http://localhost:5050       pgAdmin (admin@admin.com / admin)

Installing the Skill

Copy the bootstrap-python/ folder to your Claude Code skills directory:

cp -r bootstrap-python ~/.claude/skills/

Then use /bp in any Claude Code session to scaffold a new project.

Platform Support

Works on Windows (Git Bash / MINGW), macOS, and Linux. The skill detects the platform and uses the correct venv activation path automatically.