Get the FREE Ultimate OpenClaw Setup Guide →

bootstrap-python-service

npx machina-cli add skill gaelic-ghost/python-skills/bootstrap-python-service --openclaw
Files (1)
SKILL.md
6.0 KB

Bootstrap Python Service

Create production-oriented FastAPI starter layouts using shared uv project/workspace scaffolding.

Workflow

  1. Choose mode:
  • Project: single FastAPI service scaffold.
  • Workspace: multi-member uv workspace scaffold.
  1. Run scripts/init_python_service.sh with explicit --name and optional --path, --python, --force, --no-git-init, --initial-commit.
  2. For workspace mode, optionally pass --members and --profile-map.
  3. Verify quality checks:
  • uv run pytest
  • uv run ruff check .
  • uv run mypy .
  1. Return exact next run/test commands.

Commands

# Project mode (default)
scripts/init_python_service.sh --name my-service

# Project mode with explicit options
scripts/init_python_service.sh --name my-service --mode project --python 3.13 --path /tmp/my-service

# Workspace mode with defaults (core-lib package + api-service service)
scripts/init_python_service.sh --name platform --mode workspace

# Workspace mode with explicit members and profile mapping
scripts/init_python_service.sh \
  --name platform \
  --mode workspace \
  --members "core-lib,billing-service,orders-service" \
  --profile-map "core-lib=package,billing-service=service,orders-service=service"

# Allow non-empty target directory
scripts/init_python_service.sh --name my-service --force

# Skip git initialization
scripts/init_python_service.sh --name my-service --no-git-init

# Create initial commit
scripts/init_python_service.sh --name my-service --initial-commit

FastAPI Guidance

Use uv FastAPI integration style as primary guidance:

uv add fastapi --extra standard
uv run fastapi dev app/main.py
# optional production-style local run
uv run fastapi run app/main.py

Guardrails

  • Refuse non-empty target directories unless --force is set.
  • Require uv and git (unless --no-git-init is set and no initial commit is requested).
  • Fail when workspace-only options are used in project mode.
  • Fail when --initial-commit is used with --no-git-init.

Defaults

  • Mode: project
  • Python version: 3.13
  • Quality tooling: pytest, ruff, mypy
  • Workspace defaults (when mode is workspace):
  • Members: core-lib,api-service
  • Profiles: first member package, remaining members service

Automation Suitability

  • Codex App automation: Medium. Useful for recurring FastAPI scaffold smoke checks and regression checks.
  • Codex CLI automation: High. Strong fit for CI or scheduled scaffolder reliability checks.

Codex App Automation Prompt Template

Use $bootstrap-python-service.

Scope boundaries:
- Work only inside <REPO_PATH>.
- Create or validate scaffold output only in <TARGET_PATH>.
- Limit activity to scaffolding and verification; no unrelated refactors.

Task:
1. If <MODE:PROJECT|WORKSPACE> is PROJECT, run:
   `scripts/init_python_service.sh --name <SERVICE_NAME> --mode project --path <TARGET_PATH> --python <PYTHON_VERSION> <FORCE_FLAG> <GIT_INIT_MODE>`
2. If <MODE:PROJECT|WORKSPACE> is WORKSPACE, run:
   `scripts/init_python_service.sh --name <SERVICE_NAME> --mode workspace --path <TARGET_PATH> --python <PYTHON_VERSION> --members "<MEMBERS_CSV>" --profile-map "<PROFILE_MAP>" <FORCE_FLAG> <GIT_INIT_MODE>`
3. Validate generated checks:
   - `uv run pytest`
   - `uv run ruff check .`
   - `uv run mypy .`
4. If mode is PROJECT, also validate generated run commands:
   - `uv run fastapi dev app/main.py`
   - `uv run fastapi run app/main.py`

Output contract:
1. STATUS: PASS or FAIL
2. GENERATED_PATH: final output path
3. COMMANDS: exact commands executed
4. RESULTS: concise check outputs
5. If FAIL: short root-cause summary and minimal remediation steps

Codex CLI Automation Prompt Template

codex exec --full-auto --sandbox workspace-write --cd "<REPO_PATH>" "<PROMPT_BODY>"

Optional machine-readable variant:

codex exec --json --full-auto --sandbox workspace-write --cd "<REPO_PATH>" "<PROMPT_BODY>"

<PROMPT_BODY> template:

Use $bootstrap-python-service.
Scope is scaffolding plus verification only in <TARGET_PATH> under <REPO_PATH>.
Run the scaffold command for <MODE:PROJECT|WORKSPACE>, then run pytest, ruff, and mypy.
If project mode, confirm FastAPI dev/run commands are valid.
Return STATUS, generated path, exact command transcript, and minimal remediation on failure.

Customization Placeholders

  • <REPO_PATH>
  • <SERVICE_NAME>
  • <MODE:PROJECT|WORKSPACE>
  • <TARGET_PATH>
  • <PYTHON_VERSION>
  • <MEMBERS_CSV>
  • <PROFILE_MAP>
  • <FORCE_FLAG>
  • <GIT_INIT_MODE>

Interactive Customization Workflow

  1. Ask for mode, name, path, Python version, and git/force flags.
  2. If workspace mode, also ask for members and profile map.
  3. Return both:
  • A YAML profile for durable reuse.
  • The exact scaffold command to run.
  1. Use this precedence order:
  • CLI flags
  • --config profile file
  • .codex/profiles/bootstrap-python-service/customization.yaml
  • ~/.config/gaelic-ghost/python-skills/bootstrap-python-service/customization.yaml
  • Script defaults
  1. If users want temporary reset behavior:
  • --bypassing-all-profiles
  • --bypassing-repo-profile
  • --deleting-repo-profile
  1. If users provide no customization or profile files, keep existing script defaults unchanged.
  2. See references/interactive-customization.md for schema and examples.

Resources

scripts/

  • init_python_service.sh: thin orchestrator that delegates to bootstrap-uv-python-workspace scripts.

references/

  • conventions.md: runtime, dependency, and quality defaults.

assets/

  • README.md.tmpl: README template for service-focused output.

Source

git clone https://github.com/gaelic-ghost/python-skills/blob/main/bootstrap-python-service/SKILL.mdView on GitHub

Overview

Bootstraps production-oriented FastAPI starter layouts on macOS using a shared uv project/workspace scaffold. It covers creating a new backend/API service from scratch, scaffolding single uv service projects, or building a uv workspace with multiple members, with optional YAML-profile customization and initial tooling setup.

How This Skill Works

Run scripts/init_python_service.sh with a required --name and optional --path, --python, --mode, --force, --no-git-init, and --initial-commit. For workspace mode, include --members and --profile-map to shape the scaffold. After setup, verify quality with uv run pytest, uv run ruff check ., and uv run mypy ..

When to Use It

  • You need to create a brand-new backend/API service from scratch.
  • You want to scaffold a single uv service project quickly.
  • You require a uv workspace with multiple packages/services.
  • You want to customize scaffold defaults via layered YAML profiles.
  • You want to initialize pytest, ruff, and mypy defaults and set up git + README.md

Quick Start

  1. Step 1: Run the init script with the required --name (and optional --mode, e.g., project or workspace).
  2. Step 2: If using workspace mode, supply --members and --profile-map as needed.
  3. Step 3: Validate with: uv run pytest, uv run ruff check ., uv run mypy .; then commit if applicable.

Best Practices

  • Ensure target directory is empty or use --force to override.
  • Require uv and git unless you explicitly use --no-git-init and skip initial commit.
  • Avoid using workspace-only options in project mode to prevent conflicts.
  • Do not use --initial-commit with --no-git-init to keep workflow coherent.
  • Validate generated scaffolds with pytest, ruff, and mypy before committing.

Example Use Cases

  • scripts/init_python_service.sh --name my-service
  • scripts/init_python_service.sh --name platform --mode workspace
  • scripts/init_python_service.sh --name my-service --no-git-init
  • scripts/init_python_service.sh --name platform --mode workspace --members "core-lib,billing-service,orders-service" --profile-map "core-lib=package,billing-service=service,orders-service=service"
  • scripts/init_python_service.sh --name my-service --initial-commit

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗