FastAPI Project Skill 🧩

This skill scaffolds new FastAPI projects or upgrades existing ones with a production-ready layout and operational practices suitable for large systems.

Scope and alignment 🧭

Mandatory reads (must be loaded before using this skill):

• •Python instructions — use its identifiers when describing compliance.
• •Local-first dev baseline
• •Quality gates baseline
• •Observability logging baseline
• •AI-assisted change baseline

Inputs to confirm ✅

• •Project name and Python version
• •API surface (REST only, GraphQL, or mixed)
• •Database (SQLite/PostgreSQL) and cache (Redis/none)
• •Background jobs (Celery/Arq/RQ/none) and async worker needs
• •Deployment target (container, PaaS, serverless)
• •Environment split (local/staging/prod) and secrets strategy

Quick reference 🧠

Capabilities 🧰

1. Project scaffold (foundation)

Use this for new projects or to align an existing project with the standard layout.

Core requirements:

• •Use pyproject.toml as the single source of truth. If available, start from the template and set:
  • •project metadata (name, version, requires-python)
  • •dependency groups for dev tooling
  • •ruff, mypy, pytest configuration
• •Use uv for deterministic installs and lockfile management.
• •Pin Python in .python-version and requires-python.
• •Scaffold with a src/ layout so imports are explicit and testable.
• •Define app settings with pydantic-settings and environment variables.
• •Keep the ASGI entrypoint thin; wire routers and dependencies in main.py.

Recommended layout:

.
├── .python-version
├── pyproject.toml
├── src/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   ├── v1/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── routes/
│   │   │   │   └── schemas/
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   ├── logging.py
│   │   │   └── observability.py
│   │   ├── services/
│   │   ├── adapters/
│   │   └── health.py
└── tests/

Dependency defaults (adjust to requirements):

• •fastapi
• •uvicorn (or gunicorn + uvicorn workers for production)
• •pydantic-settings
• •httpx (for outbound HTTP)
• •pytest
• •ruff, mypy

2. Large-system structure and boundaries

Use these patterns when the system is expected to grow:

• •Group routers by domain in api/v1/routes/<domain>.py; keep routing thin.
• •Put business logic in services; keep I/O inside adapters/selectors.
• •Use dependency injection for shared concerns (auth, DB sessions, clients).
• •Use explicit schemas at boundaries; avoid leaking ORM models.
• •Separate infrastructure wiring (clients, pools) from request handling.

3. Observability baseline

Observability is non-negotiable for production workloads:

• •Configure structured logging and include required fields from the structured logging baseline.
• •Add request ID/correlation ID middleware and propagate IDs into logs.
• •Provide health endpoints (/healthz, /readyz) with clear dependency checks.
• •Add optional hooks for metrics and tracing (Prometheus or OpenTelemetry) but keep them toggled by configuration.
• •Never log secrets or raw personal data.

4. Security baseline

Protect data and enforce secure defaults:

• •Load secrets from environment or a secret manager; never commit or log secrets.
• •Configure CORS narrowly; never use * in production for credentialed routes.
• •Enforce authn/authz at router boundaries; keep public vs private APIs explicit.
• •Disable or restrict interactive docs in production when required.
• •Use dependency pinning and vulnerability scanning; keep lock files updated.

5. Resilience and availability baseline

Build for failure and recovery:

• •Set explicit timeouts on outbound HTTP/DB calls; never rely on defaults.
• •Use retries with bounded backoff and jitter for transient failures; avoid retrying non-idempotent operations without safeguards.
• •Use connection pooling and sensible concurrency limits for the ASGI server.
• •Provide graceful shutdown and ensure background tasks are interruptible.
• •Use caching for hot paths and provide safe fallbacks when caches fail.

6. Quality gates and verification

Align with Python quality gates:

• •Prefer make format, make lint, make typecheck, make test when Makefile targets exist.
• •Otherwise use uv run ruff format ., uv run ruff check ., uv run mypy ., uv run pytest.
• •Add a lightweight ASGI startup check (import app, load settings) before shipping.

Output expectations 📦

When executing this skill, produce:

• •A scaffolded FastAPI project or a concrete refactor plan for an existing codebase
• •A list of decisions made for observability, security, resilience, and availability
• •A short validation checklist using the canonical quality gates

When information is missing, record Unknown from code – {suggested action} instead of guessing.

Version: 1.0.0 Last Amended: 2026-01-18