python-project-setup

What this skill does

# Python Project Setup Skill

A specialized skill for setting up modern Python projects using uv tooling, best practices, and standardized project structures.

## Overview

This skill enables Claude to autonomously set up Python projects following modern best practices. It promotes the use of `uv` (the fast Python package manager), enforces PEP8 standards, type hints, and proper project structure with `src` layout.

## Capabilities

When activated, this skill provides:

1. **Modern Tooling with uv**
   - Use `uv` instead of pip/python directly
   - Initialize virtual environments: `uv venv`
   - Manage dependencies: `uv add`, `uv remove`
   - Sync dependencies: `uv sync`
   - Run scripts: `uv run`

2. **Project Structure Detection & Setup**
   - Detect if project is new or existing
   - Analyze current structure and adapt recommendations
   - Promote `src/package_name` layout
   - Create proper `__init__.py` files
   - Setup `__main__.py` entry points

3. **pyproject.toml Management**
   - Generate modern pyproject.toml
   - Configure project metadata
   - Setup dependencies and dev dependencies
   - Include tool configurations (ruff, mypy, pytest)
   - Define entry points for CLI applications

4. **Library Selection**
   - Present interactive menu for library choices
   - **CLI applications**: click (commands), rich (output), inquirer (interactive prompts)
   - **TUI applications**: textual (framework), rich (rendering)
   - **Pure libraries**: minimal dependencies
   - Smart recommendations based on project type

5. **Standards Enforcement**
   - PEP8 compliance via ruff
   - Type hints for all functions/methods
   - Proper docstring formats (Google/NumPy style)
   - Follow PEP8 and modern Python standards

## Usage

This skill activates automatically when:
- User requests: "Create a new Python project"
- User asks: "Setup Python project structure"
- User mentions: "Initialize Python package"
- User wants to: "Migrate to uv"
- Claude detects Python project initialization
- pyproject.toml creation or modification is discussed

**Automatic Defaults**:
- Uses current directory as project root
- Derives package name from directory name
- Detects and uses current Python version
- No tests (user can add later)
- Minimal dependencies by default

**Only ONE Question**:
- Project type + libraries combined (default: minimal)

## Project Setup Approach

### For New Projects

**IMPORTANT**: Always work in the current directory as the project root.

1. **Gather Requirements**
   - Package name (derive from current directory name by default)
   - **Ask ONE merged question**: Project type + libraries combined:
     ```
     What type of project? (press Enter for CLI with click+rich)
     [1] CLI with click+rich (default)
     [2] CLI with argparse
     [3] CLI with typer
     [4] TUI with textual
     [5] Generic Python Project
     ```
   - **Don't ask about tests** - skip by default

2. **Assume Current Directory & Python Version**
   - **Use current folder as project root** (don't create new directory)
   - Derive package name from current folder name (convert to valid Python identifier)
   - Example: `my-awesome-app/` → package name: `my_awesome_app`
   - **Detect current Python version** and use as project requirement
   - Example: `python --version` → `Python 3.11.5` → `requires-python = ">=3.11"`

3. **Check Environment**
   ```bash
   # Detect current Python version
   python --version  # Use this as the project's Python requirement

   # Verify uv is installed
   uv --version

   # If not installed, provide instructions:
   # macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   # Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```

4. **Create Minimal Project Structure in Current Directory**
   ```
   ./                           # Current directory (project root)
   ├── src/
   │   └── package_name/
   │       ├── __init__.py
   │       └── __main__.py      # Entry point
   ├── pyproject.toml           # Minimal config
   ├── README.md
   └── .gitignore
   ```

   **Note**: No tests/, no .python-version - keep it minimal!

5. **Skip Tests by Default**
   - Do NOT ask about tests
   - Do NOT create tests/ directory
   - Do NOT include pytest in dev dependencies
   - User can add tests later if needed

6. **Generate Minimal pyproject.toml**
   ```toml
   [project]
   name = "package-name"
   version = "0.1.0"
   description = "Project description"
   authors = [
       {name = "Author Name", email = "[email protected]"}
   ]
   readme = "README.md"
   requires-python = ">=3.11"  # Use detected Python version (e.g., 3.11, 3.12, etc.)
   dependencies = [
       # Based on library selection
   ]

   [project.optional-dependencies]
   dev = [
       "ruff>=0.1.0",
       "mypy>=1.8.0",
   ]
   # Note: No pytest by default - add when needed

   [project.scripts]
   package-name = "package_name.__main__:main"

   [build-system]
   requires = ["hatchling"]
   build-backend = "hatchling.build"

   [tool.ruff]
   line-length = 88
   target-version = "py311"
   select = ["E", "F", "I", "N", "W", "UP"]

   [tool.mypy]
   python_version = "3.11"
   strict = true
   warn_return_any = true
   warn_unused_configs = true

   [tool.pytest.ini_options]
   testpaths = ["tests"]
   python_files = ["test_*.py"]
   ```

8. **Initialize with uv in Current Directory**
   ```bash
   # Already in project directory (current folder)

   # Create virtual environment
   uv venv

   # Sync dependencies from pyproject.toml
   uv sync

   # Add project in editable mode
   uv pip install -e .

   # Add development dependencies (includes pytest if tests opted in)
   uv sync --group dev
   ```

9. **Create Entry Point Examples**

   For `src/package_name/__main__.py`:
   ```python
   """Main entry point for package_name."""

   def main() -> None:
       """Execute the main program."""
       print("Hello from package_name!")

   if __name__ == "__main__":
       main()
   ```

   For CLI apps with click:
   ```python
   """Main entry point for package_name CLI."""

   import click
   from rich.console import Console

   console = Console()

   @click.group()
   @click.version_option()
   def main() -> None:
       """Package name CLI application."""
       pass

   @main.command()
   @click.option("--name", default="World", help="Name to greet")
   def hello(name: str) -> None:
       """Greet someone."""
       console.print(f"[bold green]Hello, {name}![/bold green]")

   if __name__ == "__main__":
       main()
   ```

### For Existing Projects

**IMPORTANT**: Always work in the current directory, don't create subdirectories.

1. **Analyze Current Directory Structure**
   - Check for setup.py, requirements.txt, or pyproject.toml
   - Identify current package structure
   - Assess if src layout is used
   - **Detect existing tests/** directory

2. **Detect Context**
   - Is uv already being used?
   - What's the current dependency management approach?
   - Are there existing entry points?
   - **Are tests already present?** (skip test skeleton question if yes)

3. **Skip Tests Question**
   - Do NOT ask about tests for existing projects
   - User can add tests manually if needed

4. **Provide Migration Path**
   ```bash
   # Already in project directory (current folder)

   # Convert requirements.txt to pyproject.toml
   # Create pyproject.toml with [project.dependencies]

   # Initialize uv for existing project
   uv venv

   # Import existing requirements
   uv pip install -r requirements.txt

   # Generate lock file
   uv sync
   ```

5. **Recommend Structure Improvements**
   - Suggest moving to src layout if not present
   - Identify missing __init__.py files
   - Recommend adding __main__.py if needed
   - Suggest adding type hints if missing

6. **Adapt, Don't Force**
   - Respect existing conventions if reasonable
   - Provide gradual migration suggestions
   - Explain benefits of each recommendation

## Output Format

Provide setup results in