Create Py Project

Create Python Project

Create, set up, bootstrap, or scaffold modern Python projects with best-in-class tooling.

ALWAYS use this skill when the user wants to:

• Set up, initialize, configure, or create ANY Python project from scratch
• Create FastAPI applications, APIs, microservices, web services, or REST APIs
• Build CLI tools, command-line utilities, or terminal applications
• Initialize Python packages, libraries, or modules
• Configure project tooling (poetry, uv, ruff, mypy, pytest, pre-commit)
• Start a new Python codebase or repository
• Scaffold project structure with proper configuration files

Trigger on these phrases and contexts:

• "set up", "setup", "initialize", "init", "scaffold", "bootstrap", "configure"
• "create project", "new project", "start project", "from scratch"
• "FastAPI", "API", "microservice", "web service", "REST API", "backend"
• "CLI tool", "command line", "terminal app", "script"
• "project structure", "project setup", "tooling", "configuration"
• Any mention of starting a new Python codebase with specific requirements

Use this skill even if the user:

• Doesn't explicitly say "bootstrap" or "initialize"
• Just describes what they want to build (e.g., "I need an API for X")
• Mentions the current directory/project needs Python setup
• Asks about project structure or best practices for a new project

This skill generates complete, working projects with pyproject.toml, main.py, package structure, router setup (for FastAPI), pre-commit hooks, linting/formatting config, and all starter files. It intelligently extracts requirements from user requests and auto-executes when intent is clear.

Company Python Conventions

All agents must follow these architectural conventions when generating projects:

Directory Structure

• shared/ - Cross-cutting shared modules and weak models
  • Clients (API clients, database clients, external service wrappers)
  • Utilities and helpers
  • Weak models (DTOs, data transfer objects, simple data structures)
  • Infrastructure concerns (logging, config, observability)
• modules/ - Strong models and domain services
  • Domain models with business logic
  • Services that utilize underlying shared/ clients
  • Business logic and domain operations
  • Use cases and application services

Architecture Principles

Follow these principles when generating code and structure:

• KISS (Keep It Simple, Stupid) - Prefer simple, straightforward solutions
• YAGNI (You Aren't Gonna Need It) - Don't add functionality until needed
• DevEx (Developer Experience) - Optimize for developer productivity and clarity
• Clean Architecture - Separate concerns, dependency inversion, domain-centric
• Orthogonal - Components should be independent and composable
• Practical - Pragmatic solutions over theoretical purity
• DDD (Domain-Driven Design) - Model the domain, ubiquitous language, bounded contexts

Import Conventions

CRITICAL: Avoid from __future__ import ... statements

Organize projects to be orthogonal and prevent circular imports instead:

• Use proper layering: modules/ depends on shared/, never the reverse
• Avoid circular dependencies by extracting shared logic to shared/
• Use dependency inversion: define interfaces/protocols in shared/, implement in modules/
• Use modern Python type hints directly (e.g., list[str], dict[str, Any])
• Orthogonal design eliminates the need for __future__ imports

Application to Generated Projects

When generating FastAPI projects:

• shared/ - Create actual implementation files:
  • shared/config.py - Settings/configuration using pydantic-settings
  • shared/{domain}_client.py - API clients for external services
  • shared/router.py - FastAPI routers (can be split into multiple files)
  • shared/models.py - DTOs, request/response models (weak models)
• modules/ - Create domain services that use shared clients:
  • modules/{domain}_service.py - Business logic that uses clients from shared/
  • modules/models.py - Domain models with business logic (strong models)
• {package_name}/ - Keep minimal (usually just __init__.py)
• Routers can import from both shared/ (for clients, config) and modules/ (for services)

When generating CLI projects:

• shared/ - Create utilities and helpers:
  • shared/file_utils.py - File I/O operations
  • shared/api_client.py - External API clients if needed
  • shared/config.py - Configuration management
• modules/ - Create core business logic:
  • modules/{domain}_processor.py - Business logic that uses shared utilities
  • modules/models.py - Domain models
• {package_name}/ - Keep minimal (usually just __init__.py)

Example: FastAPI Project Structure

my-api/
├── main.py                      # FastAPI app, includes routers
├── pyproject.toml
├── my_api/                      # Package (minimal)
│   └── __init__.py
├── shared/                      # Infrastructure layer
│   ├── __init__.py
│   ├── config.py               # Settings (API keys, URLs, etc.)
│   ├── {domain}_client.py      # HTTP client for external API
│   └── router.py               # FastAPI routes
└── modules/                     # Domain layer
    ├── __init__.py
    ├── {domain}_service.py     # Business logic using client from shared/
    └── models.py               # Domain models

What Gets Generated

Core Files (Always):

• pyproject.toml - Full project config with dependencies and tool settings
• main.py - Entry point (CLI or FastAPI with lifespan)
• .pre-commit-config.yaml - Git hooks configured for your type checker choice
• .gitignore - Python-specific ignores
• .env.example - Environment template with relevant variables for your project
• README.md - Complete documentation with accurate commands
• Justfile - Task runner with common commands
• .python-version - Python version (if pyenv detected)

Package Structure (Always):

• {package_name}/__init__.py - Package initialization (usually minimal/empty)
• shared/__init__.py - Shared modules directory (cross-cutting concerns, weak models)
• modules/__init__.py - Modules directory (domain models, business services)

Additional Files Based on Project Type:

• FastAPI projects: Create actual implementation files in shared/ (clients, config, routers)
• CLI projects: Create actual implementation files in shared/ (utilities, helpers) and modules/ (business logic)

All files contain working, customized content - not placeholder text or generic templates.

CRITICAL: Directory structure follows company conventions:

• shared/ for infrastructure, clients, utilities, weak models - ALWAYS CREATE WITH ACTUAL FILES
• modules/ for domain logic, business services, strong models - ALWAYS CREATE, populate based on domain
• {package_name}/ is typically minimal (just __init__.py) - NOT the main code location

Tool Stack

• Package Manager: poetry (default) or uv
• Linter/Formatter: ruff (replaces black, flake8, isort, pydocstyle)
• Type Checker: mypy (default) or ty
• Testing: pytest
• Git Hooks: pre-commit

Ruff Configuration

Uses the proven rule set from production projects:

• Select: E, F, W (flake8), I (isort), UP (pyupgrade), PL (pylint), B (bugbear), S (bandit), C90 (mccabe), D (pydocstyle)
• Line length: 88 (black-compatible)
• Target Python: Matches project version
• Per-file ignores: Tests, scripts, alembic

Workflow

1. Preflight Confirmation: Ask whether to use all defaults
2. Gather Requirements: Collect user preferences and nuanced requirements
3. Dynamic Generation: File Generator agent creates customized, working files
4. Validation: Project Validator ensures correctness and completeness
5. Fix Loop (if needed): Coordinate fixes until validation passes
6. Initialize Environment: Install dependencies with chosen package manager
7. Runtime Validation: Run linting/formatting to verify setup
8. Next Steps: Provide tailored guidance for the specific project

Agent-Driven Architecture

This skill uses three specialized agents working together:

1. Setup Coordinator (Orchestrator)

• Gathers user requirements and preferences
• Interprets nuanced customization requests
• Delegates to File Generator and Project Validator
• Coordinates fix loops until validation passes
• Manages environment setup and tooling

2. File Generator (Content Creator)

• Generates all project files with appropriate, working content
• Adapts to user's specific needs (not rigid templates)
• Ensures all code is syntactically correct and complete
• Customizes based on project type, dependencies, and user intent
• Examples:
  • User mentions "Redis" → adds Redis deps, connection code, env vars
  • User mentions "auth" → adds JWT deps, auth routes, security examples
  • User mentions "database" → adds ORM deps, connection setup, migration hints

3. Project Validator (Quality Assurance)

• Validates all generated files for correctness
• Checks syntax, imports, configuration consistency
• Ensures no placeholder text remains
• Verifies type hints match Python version
• Reports findings without editing files

Agents

This skill includes specialized agents for different tasks:

Setup Coordinator (agents/setup-coordinator.md)

Purpose: Orchestrate the entire bootstrap process with flexible customization.

Responsibilities:

• Gather user requirements (8 configuration questions with smart defaults)
• Interpret nuanced customization requests
• Delegate file generation to File Generator agent
• Coordinate validation with Project Validator agent
• Handle edge cases (existing files, missing tools, version conflicts)
• Manage environment setup and dependency installation
• Provide tailored next steps

Key Feature: Understands nuanced user intent and passes it to File Generator for customization.

File Generator (agents/file-generator.md)

Purpose: Dynamically generate all project files with appropriate, working content.

Responsibilities:

• Generate pyproject.toml with correct dependencies and configuration
• Create main.py with working entry point (CLI or FastAPI)
• Generate package structure with proper imports
• Create pre-commit config matching type checker choice
• Generate .env.example with relevant variables
• Create comprehensive README.md with accurate commands
• Generate Justfile with correct task definitions

Key Feature: Adapts content based on user's specific needs, not rigid templates.

Customization Examples:

• "API with Redis caching" → adds httpx, redis deps; Redis connection in lifespan; domain-specific routes
• "CLI for data processing" → adds pandas, argparse setup; file I/O examples
• "Strict type checking" → configures mypy strictest settings; 100% coverage requirement

Project Validator (agents/project-validator.md)

Purpose: Comprehensively validate generated project files.

Validation Checks:

• All required files exist
• pyproject.toml is valid TOML with correct dependencies
• Python files have valid syntax (AST parseable)
• All imports are available in dependencies or stdlib
• YAML files are valid
• Package structure is correct
• Configuration is consistent across files
• No placeholder text remains
• Type hints match Python version
• README commands match package manager

Key Feature: Reports findings only; Setup Coordinator coordinates fixes.

Step 1: Gather Requirements

1.0 Smart Preflight Decision

Before asking any questions, analyze the user's request to determine if requirements are explicit.

Auto-Execute Conditions (minimal or no questions)

If the user's request contains explicit project requirements, immediately proceed to file generation. Extract settings from their request and infer reasonable defaults for anything not specified.

When to auto-execute without questions:

• Request is clear and unambiguous
• All critical settings can be confidently inferred
• No conflicting requirements

When to use ask_user_question for quick clarification (even in auto-execute mode):

• Ambiguous project name (use ask_user_question with text input)
• Unclear if FastAPI or CLI when both could fit
• Multiple valid interpretations of tech stack
• User mentions both poetry and uv

Explicit requirement indicators:

• Project type mentioned: "FastAPI", "API", "microservice", "web service", "CLI tool", "package"
• Specific purpose/domain: "data processing", "authentication service", "API integration"
• Technology stack mentioned: "Redis", "PostgreSQL", "JWT", "database"
• Package manager mentioned: "poetry", "uv"

Examples that should auto-execute:

• "Set up a FastAPI microservice for {specific purpose}" → auto-execute, no questions
• "Create a CLI tool for data processing with pandas" → auto-execute, no questions
• "Bootstrap an API with Redis caching" → auto-execute, no questions
• "Initialize a Python package for authentication with JWT" → auto-execute, no questions

Inferred settings for auto-execute:

• FastAPI/API/microservice/web service → is_fastapi=true
• CLI/tool/package → is_fastapi=false
• Mentioned tech → add to dependencies
• Package manager mentioned → use that tool, otherwise poetry
• Python version → 3.13 (unless specified)
• Type checker → mypy (unless specified)
• Description → derive from user's stated purpose
• Project name → derive from directory name or purpose if clear

Interactive Mode (use ask_user_question)

If the user's request is vague or generic, enter interactive mode and use ask_user_question for all questions. If the user's request don't cover one of the specific questions required for generating a project, then use ask_user_question to ask for that information (one question at a time), if ask_user_question type tooling is not available (check), then ask via chat.

Vague request examples:

• "Set up a Python project"
• "Bootstrap this project"
• "Initialize Python tooling"
• "Create a new project"

Interactive flow:

1. Check if ask_user_question is available (it should be in Windsurf/Cascade)
2. Ask preflight question using ask_user_question:
   • Question: Use default bootstrap settings?
   • Options: ["yes", "no"]
   • Default: "yes"
3. If user says "yes": Proceed with defaults, show config preview
4. If user says "no": Run full requirement-gathering flow using ask_user_question for all questions (see section 1.1 below)

Default settings:

• Package manager: poetry
• Python version: 3.13
• Type checker: mypy
• FastAPI: no
• Description: A Python project
• Dependencies: none
• Dev dependencies: none (beyond built-in defaults)

Tool usage:

• In Windsurf/Cascade, ALWAYS use ask_user_question for requirement gathering
• Treat it as the primary interaction path for this skill in IDE environments
• Only fall back to plain chat questions if ask_user_question is truly unavailable or returns a tool-not-found/error

If ask_user_question is available

Use ask_user_question in menu/select mode for questions with ≤4 discrete options. This reduces friction and prevents typing errors.

Questions to ask via menu

1. Package manager (menu): poetry (default) vs uv
2. Python version (menu): 3.12, 3.13 (default), or Other
3. Type checker (menu): mypy (default), ty, or none
4. FastAPI project? (menu): no (default), yes

Questions to ask via text (free-form input)

1. Project name: Free text (derive from directory if empty)
2. Description: Free text (default: "A Python project")
3. Dependencies: Comma-separated list
4. Dev dependencies: Comma-separated list

If ask_user_question is not available

Ask questions sequentially, one at a time to reduce communication friction. Do not present all questions at once.

Flow

1. Ask Use default bootstrap settings? [Y/n] first.
2. If yes, proceed with defaults and show a config preview before generation.
3. If no, ask first setup question → Wait for answer.
4. Ask second setup question → Wait for answer.
5. Continue until all 8 setup questions are answered.

This sequential approach prevents the user from feeling overwhelmed and allows for context-specific follow-ups.

Questions Reference

Default dev dependencies always included:

• pytest
• pytest-asyncio
• ruff
• pre-commit

Additional defaults if type checker selected:

• mypy or ty (based on choice)

Additional defaults if FastAPI:

• fastapi[standard]
• uvicorn
• pydantic

Step 2: Generate Files

2.1 Read Templates

Read the appropriate templates from the skill's templates/ directory based on user choices:

templates/
├── pyproject-poetry.toml
├── pyproject-uv.toml
├── main-simple.py
├── main-fastapi.py
├── package_init.py
├── shared_router.py
├── pre-commit.yaml
├── gitignore
├── env.example
├── readme.md
└── justfile

2.2 Render Templates

Substitute these variables into templates using simple string replacement ({{ variable }}):

2.3 Write Files

Write these files to the target directory:

Step 3: Initialize Environment

Prerequisite:

• Project Validator must have returned valid: true.

Run the appropriate commands based on tool choice:

If Poetry

poetry install

If uv

uv venv
uv pip install -e ".[dev]"

Step 4: Validate Setup

Run initial formatting and linting:

If Poetry (validation)

poetry run ruff check --fix .
poetry run ruff format .

If uv (validation)

uv run ruff check --fix .
uv run ruff format .

Note:

• This step validates runtime tooling (ruff/formatting) after structural validation has already passed.

Step 5: Live Test (Optional)

After validation passes, offer to run a live test of the application:

1. Use ask_user_question to ask:

   • Question: "Would you like me to run a live test of the application?"
   • Options: ["yes", "no"]
   • Default: "yes"

2. If user says "yes":

   For FastAPI projects:

   • Start the server in the background: poetry run python main.py or uv run python main.py

   • Wait for server startup (check for "Application startup complete" or similar)

   • Test endpoints with curl:

     # Test health endpoint
     curl -s http://localhost:8000/health || echo "Health check failed"
     
     # Test root endpoint
     curl -s http://localhost:8000/ || echo "Root endpoint failed"
     
     # For APIs with specific routes, test those too
     # Example: curl -s http://localhost:8000/api/weather/current?city=Seattle&state=WA
     

   • Report results to user (success/failure for each endpoint)

   • Stop the server (send SIGTERM or use process management)

   For CLI projects:

   • Run the CLI with --help to verify it works: poetry run python main.py --help
   • If applicable, run a quick test with sample inputs
   • Report results to user

3. If user says "no":

   • Skip to Step 6

Step 6: Print Next Steps

Show the user:

✅ Project "{project_name}" bootstrapped successfully!

📁 Files created:
   - pyproject.toml (project config)
   - main.py (entry point)
   {shared/router.py if FastAPI}
   - .pre-commit-config.yaml (git hooks)
   - .gitignore
   - .env.example
   - README.md

🚀 Next steps:
   1. cd {directory}
   2. {poetry shell / source .venv/bin/activate}
   3. cp .env.example .env  # Edit with your values
   4. {poetry run python main.py / uv run python main.py}

📦 To add dependencies:
   {poetry add <package> / uv add <package>}

🔧 Tools configured:
   - ruff: linting & formatting (run: {poetry run ruff check . / uv run ruff check .})
   - {mypy/ty}: type checking (run: {poetry run mypy . / uv run mypy .})
   - pytest: testing (run: {poetry run pytest / uv run pytest})
   - pre-commit: git hooks (run: pre-commit install)

Template Reference

pyproject.toml Structure (Poetry)

[project]
name = "{project_name}"
version = "0.1.0"
description = "{project_description}"
readme = "README.md"
requires-python = ">={python_version}"
dependencies = [
    # User-specified dependencies
]

[project.scripts]
{project_name} = "{project_name}.main:main"

[tool.poetry]
packages = [{include = "{project_name}"}]

[tool.poetry.group.dev.dependencies]
pytest = "*"
pytest-asyncio = "*"
ruff = "*"
pre-commit = "*"
# Type checker if selected
# User-specified dev dependencies

[tool.ruff]
line-length = 88
target-version = "py{python_version_nodot}"

[tool.ruff.format]
quote-style = "double"
docstring-code-format = true

[tool.ruff.lint]
ignore = [
    "E203",
    "S110",
    "D100",
    "D104",
    "D107",
    "D203",
    "D213",
    "D105",
]
select = [
    "E", "F", "W",
    "I",
    "UP",
    "PL",
    "B",
    "S",
    "C90",
    "D"
]

[tool.ruff.lint.per-file-ignores]
"**/tests/**" = ["S101", "PLR2004"]
"**/test_*.py" = ["S101"]

[tool.ruff.lint.pylint]
max-args = 6

[tool.ruff.lint.mccabe]
max-complexity = 13

[tool.mypy]
# If mypy selected
strict = true
warn_return_any = true
warn_unused_ignores = true

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

main.py (FastAPI)

from contextlib import asynccontextmanager
from collections.abc import AsyncIterator

import uvicorn
from fastapi import FastAPI

from shared.router import router as api_router


@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
    """Application lifespan handler."""
    # Startup
    yield
    # Shutdown


app = FastAPI(lifespan=lifespan)


@app.get("/")
async def index() -> dict[str, str]:
    """Root endpoint."""
    return {"message": "Hello from {project_name}!"}


app.include_router(api_router, prefix="/api")


if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

shared/router.py

from fastapi import APIRouter, status
from fastapi.responses import JSONResponse

router = APIRouter()


@router.get("/health")
async def health() -> JSONResponse:
    """Health check endpoint."""
    return JSONResponse(content={"status": "healthy"}, status_code=status.HTTP_200_OK)

.pre-commit-config.yaml

repos:
  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.14.11
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.15.0
    hooks:
      - id: mypy
        args: [--strict]