name	python-project-setup
description	Sets up modern Python projects with uv tooling, src layout, and PEP8 standards. Handles both new and existing projects, presents interactive library selection for CLI/TUI apps, generates pyproject.toml, and provides complete scaffolding with type hints and proper structure.

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:

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
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
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
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
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.

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

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"

Check Environment

# 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"

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!

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

Generate Minimal pyproject.toml

[project]
name = "package-name"
version = "0.1.0"
description = "Project description"
authors = [
    {name = "Author Name", email = "author@example.com"}
]
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"]

Initialize with uv in Current Directory

# 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

Create Entry Point Examples

For src/package_name/__main__.py:

"""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:

"""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.

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
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)
Skip Tests Question
- Do NOT ask about tests for existing projects
- User can add tests manually if needed

Provide Migration Path

# 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

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
Adapt, Don't Force
- Respect existing conventions if reasonable
- Provide gradual migration suggestions
- Explain benefits of each recommendation

Output Format

Provide setup results in this format:

## Python Project Setup Complete

### Project Directory
**Working in**: `./` (current directory)
**Package name**: `package_name`

### Project Structure
[Show created directory tree relative to current directory]

### Configuration
- **Python version**: [Detected from current environment, e.g., 3.11+]
- **Package manager**: uv
- **Layout**: src layout
- **Entry point**: src/package_name/__main__.py
- **Tests**: Not included (add later if needed)

### Dependencies Installed
**Main dependencies:**
- [list dependencies]

**Development dependencies:**
- ruff (linting)
- mypy (type checking)

### Next Steps
1. Activate virtual environment:
   \`\`\`bash
   source .venv/bin/activate  # Linux/macOS
   .venv\\Scripts\\activate     # Windows
   \`\`\`

2. Run your application:
   \`\`\`bash
   uv run python -m package_name
   # or
   uv run package-name
   \`\`\`

3. Add new dependencies:
   \`\`\`bash
   uv add package-name
   \`\`\`

4. Lint code:
   \`\`\`bash
   uv run ruff check .
   uv run mypy src
   \`\`\`

### Development Commands
- Add dependency: `uv add package-name`
- Add dev dependency: `uv add --dev package-name`
- Remove dependency: `uv remove package-name`
- Update dependencies: `uv sync`
- Run script: `uv run python script.py`

Standards Enforced

Always Use uv Commands

❌ pip install package
✅ uv add package
❌ pip install -r requirements.txt
✅ uv sync
❌ python script.py
✅ uv run python script.py
❌ python -m venv .venv
✅ uv venv

Project Structure Standards

src/package_name/          # Use src layout
├── __init__.py           # Package marker (can be empty or contain version)
├── __main__.py           # Entry point with main() function
├── module1.py            # Application modules
└── module2.py

Code Standards

All functions must have type hints
Use """Docstrings""" for all public functions/classes
Follow PEP8 (enforced by ruff)
Line length: 88 characters (Black standard)
Use absolute imports from package root

Example Type-Hinted Code

from typing import Optional

def process_data(
    input_data: list[str],
    max_items: int = 10,
    filter_empty: bool = True
) -> dict[str, int]:
    """Process input data and return statistics.

    Args:
        input_data: List of strings to process
        max_items: Maximum number of items to process
        filter_empty: Whether to filter out empty strings

    Returns:
        Dictionary with processing statistics
    """
    result: dict[str, int] = {}
    # Implementation
    return result

Library Recommendations

For CLI Applications

dependencies = [
    "click>=8.1.0",      # Command-line interface framework
    "rich>=13.7.0",      # Beautiful terminal output
    "inquirer>=3.2.0",   # Interactive prompts
]

For TUI Applications

dependencies = [
    "textual>=0.47.0",   # Modern TUI framework
    "rich>=13.7.0",      # Rendering engine
]

For Libraries

dependencies = [
    # Only essential dependencies
    # Keep it minimal
]

Best Practices

Work in current directory - Don't create nested project folders
Use current Python version - Detect from environment, don't ask
Ask one merged question - Project type + libraries combined
Start with minimal dependencies - Add more as needed
Always include type hints - Helps with IDE support and catches bugs
Use src layout - Prevents import issues and packaging problems
Pin major versions only - e.g., >=8.1.0 not ==8.1.0
Separate dev dependencies - Use [project.optional-dependencies]
Document with docstrings - Every public function and class
Don't ask about tests - Skip by default, users add when ready
Use ruff for linting - Fast, comprehensive, replaces flake8/isort/black

Common Patterns

CLI Application with Click + Rich

import click
from rich.console import Console
from rich.table import Table

console = Console()

@click.command()
@click.argument("name")
@click.option("--count", default=1, help="Number of greetings")
def greet(name: str, count: int) -> None:
    """Greet NAME COUNT times."""
    for _ in range(count):
        console.print(f"[bold blue]Hello, {name}![/bold blue]")

TUI Application with Textual

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Button

class MyApp(App):
    """A simple Textual application."""

    def compose(self) -> ComposeResult:
        yield Header()
        yield Button("Click me!", id="btn")
        yield Footer()

    def on_button_pressed(self, event: Button.Pressed) -> None:
        """Handle button press."""
        self.notify("Button clicked!")

if __name__ == "__main__":
    app = MyApp()
    app.run()

Integration

This skill works seamlessly with:

New Python project creation
Existing project modernization
Migration from pip to uv
Package structure refactoring
Dependency management tasks

python-project-setup

Install Skill

SKILL.md