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 askuserquestion)

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"

1. If user says "yes": Proceed with defaults, show config preview
2. 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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rapid-recovery-agency-inc
• Source: rapid-recovery-agency-inc/agents-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.