Generate FastAPI project scaffold with uvicorn, OpenAPI docs, and configuration management
/plugin marketplace add pborenstein/plinth/plugin install pborenstein-plinth@pborenstein/plinthThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdtemplates/README.md.templatetemplates/__init__.py.templatetemplates/__main__.py.templatetemplates/__version__.py.templatetemplates/config.example.json.templatetemplates/config.py.templatetemplates/pyproject.toml.templatetemplates/server.py.templateGenerate a complete FastAPI project structure with modern Python tooling (uv, FastAPI, uvicorn) following best practices from temoa and apantli projects.
A production-ready FastAPI project with:
{PROJECT_NAME}/
├── pyproject.toml
├── config.example.json
├── {PACKAGE_NAME}/
│ ├── __init__.py
│ ├── __version__.py
│ ├── __main__.py
│ ├── server.py
│ └── config.py
├── .gitignore
├── .env.example
└── README.md
Collect the following information from the user (use AskUserQuestion if needed):
Required parameters:
PROJECT_NAME (string) - Display name (e.g., "Temoa", "Apantli")
PACKAGE_NAME (string) - Python package name (e.g., "temoa", "apantli")
DESCRIPTION (string) - One-line project description
Optional parameters (with defaults):
SERVER_HOST (string) - Default: "0.0.0.0"
SERVER_PORT (integer) - Default: 8000
PYTHON_VERSION (string) - Default: ">=3.11"
VERSION (string) - Default: "0.1.0"
From the collected parameters, derive:
Create the project root directory:
Path(PROJECT_NAME).mkdir(exist_ok=True)
Create the Python package directory:
Path(PROJECT_NAME) / PACKAGE_NAME).mkdir(exist_ok=True)
For each template file in skills/fastapi-scaffold/templates/:
{{PROJECT_NAME}} → PROJECT_NAME{{PACKAGE_NAME}} → PACKAGE_NAME{{PACKAGE_NAME_UPPER}} → PACKAGE_NAME_UPPER{{DESCRIPTION}} → DESCRIPTION{{SERVER_HOST}} → SERVER_HOST{{SERVER_PORT}} → SERVER_PORT (as string){{PYTHON_VERSION}} → PYTHON_VERSION{{VERSION}} → VERSIONTemplate mapping:
| Template | Target Location |
|---|---|
__init__.py.template | {PROJECT_NAME}/{PACKAGE_NAME}/__init__.py |
__version__.py.template | {PROJECT_NAME}/{PACKAGE_NAME}/__version__.py |
server.py.template | {PROJECT_NAME}/{PACKAGE_NAME}/server.py |
__main__.py.template | {PROJECT_NAME}/{PACKAGE_NAME}/__main__.py |
config.py.template | {PROJECT_NAME}/{PACKAGE_NAME}/config.py |
pyproject.toml.template | {PROJECT_NAME}/pyproject.toml |
.gitignore.template | {PROJECT_NAME}/.gitignore |
.env.example.template | {PROJECT_NAME}/.env.example |
config.example.json.template | {PROJECT_NAME}/config.example.json |
README.md.template | {PROJECT_NAME}/README.md |
Confirm all files were created successfully:
ls -la {PROJECT_NAME}/
ls -la {PROJECT_NAME}/{PACKAGE_NAME}/
Expected: 10 files total (3 in root, 5 in package, 2 dotfiles)
Ask the user if they want to initialize a git repository:
cd {PROJECT_NAME}
git init
git add .
git commit -m "Initial commit: FastAPI project scaffold"
Guide the user through initial setup:
cd {PROJECT_NAME}
# Install dependencies
uv sync
# Create config from example
cp config.example.json config.json
Provide verification commands and next steps:
# Verify installation
uv run {PACKAGE_NAME} --version
# Run development server
uv run {PACKAGE_NAME} --reload
# Open in browser
open http://localhost:{SERVER_PORT}/docs
| Variable | Example | Description |
|---|---|---|
{{PROJECT_NAME}} | "MyAPI" | Display name for documentation |
{{PACKAGE_NAME}} | "myapi" | Python package name (lowercase) |
{{PACKAGE_NAME_UPPER}} | "MYAPI" | Uppercase for env vars |
{{DESCRIPTION}} | "API for data" | One-line description |
{{SERVER_HOST}} | "0.0.0.0" | Default server host |
{{SERVER_PORT}} | "8000" | Default server port |
{{PYTHON_VERSION}} | ">=3.11" | Python version requirement |
{{VERSION}} | "0.1.0" | Initial project version |
User request: "Create a FastAPI project for my blog API"
Parameters collected:
Derived:
Generated structure:
BlogAPI/
├── pyproject.toml
├── config.example.json
├── blogapi/
│ ├── __init__.py
│ ├── __version__.py
│ ├── __main__.py
│ ├── server.py
│ └── config.py
├── .gitignore
├── .env.example
└── README.md
Verification:
cd BlogAPI
uv sync
uv run blogapi --version # → "BlogAPI 0.1.0"
uv run blogapi --reload # → Server at http://0.0.0.0:8080
If PACKAGE_NAME contains invalid characters (spaces, hyphens in wrong places), normalize it:
package_name = PROJECT_NAME.lower().replace(" ", "_").replace("-", "_")
Suggest the user choose a different port if the default is occupied.
If uv is not installed, guide the user:
brew install uv
After generating the scaffold, users typically:
server.pypyproject.toml and run uv sync/macos-launchd-service skill{{VARIABLE}} syntax for substitution