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 🧠

pyproject.toml

src/

make

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