name	python
description	Python development standards, tools, design patterns. Use when creating Python scripts, writing .py files, implementing PEP 723 scripts with inline dependencies, formatting Python code, setting up projects with UV, applying design patterns, or when user mentions Python styleguide, Ruff, UV, uv run, type hints, or Python best practices.

Python Development Skill

Comprehensive Python development skill with modern tooling, researched styleguide, and 40 design patterns.

Capabilities

Styleguide: PEP 8 + Black (88 chars) + Ruff + Google docstrings (evidence-based)
Modern Tools: Ruff (linter/formatter), UV (package manager, 10-100x faster)
Design Patterns: 40 patterns from python-patterns (42.3k stars) - creational, structural, behavioral
PEP 723 Scripts: Self-contained scripts with inline dependencies
Universal Templates: Portable boilerplate for CLI, libraries, scripts, tests

When to Use

Trigger phrases:

"Python styleguide"
"Format Python code"
"Set up Python project"
"Use UV" / "Use Ruff"
"PEP 723 script"
"Python design patterns"
"Factory pattern" / "Singleton" / "Observer" (any pattern name)

Actions:

Load styleguide recommendations (resources/styleguide.md)
Reference tool quick reference (resources/ruff.md, resources/uv.md)
Apply design pattern (patterns/{category}/*.py)
Create PEP 723 script with inline dependencies
Link to official docs for deep dives

Styleguide (Quick Reference)

Modern Python styleguide (2025) - researched, evidence-based recommendation.

Core decisions:

Line length: 88 characters (Black standard, Django/FastAPI adoption)
Quotes: Double quotes "string" (Black default, consistency)
Imports: Absolute imports, grouped (stdlib → third-party → local)
Type hints: PEP 484 signatures (not docstrings)
Docstrings: Google style (clear structure, widely adopted)
Formatter: Ruff format (Black-compatible, 10-100x faster)

Why this choice:

Community consensus: Django, FastAPI, and majority of modern projects
Tool ecosystem: Ruff defaults to Black-compatible mode
Evidence-based: Black's research showed 88 chars = ~10% shorter files vs 79
Enforceability: Single formatter (Ruff) replaces 6 tools

Full details: See resources/styleguide.md (338 lines with research citations)

Refactoring Testing Strategy

Safe refactoring workflow for Python code

Testing Levels

1. Baseline (establish working state):

# Before changing code
mypy src/ | tee /tmp/mypy-before.txt
ruff check src/ | tee /tmp/ruff-before.txt
# Run integration tests (e.g., /commit for acf-git)

2. Incremental (test after each change):

# After creating each class/module
python -c "from package.module import NewClass"  # Imports work?
mypy src/package/module.py  # No new type errors?

3. Regression (compare to baseline):

# After refactoring
mypy src/ | grep -c "error:"  # Should be ≤ baseline
ruff check src/ | grep -c "Found"  # Should be ≤ baseline

4. Integration (end-to-end workflows):

# Test actual workflows, NOT standalone scripts
# Example: /commit workflow (not generate_commit_v2.py directly)
# Example: Session detection workflow (not detect_session_type.py directly)

Pattern-Specific Validation

Factory Pattern:

Factory class creates all handler types
Handlers implement common interface
Integration point uses factory (not direct instantiation)

Strategy Pattern:

All strategies implement same interface
Strategy selection works
Context uses strategies correctly

Singleton/Registry:

Single instance verified
Thread-safety if needed

Rollback on Failure

# If tests fail after change
git reset --hard HEAD~1  # Undo last commit
# Or
git checkout -- file.py  # Undo unstaged changes

See also: Skill("git") - resources/refactoring-safety.md

Tools

Ruff - All-in-One Linter & Formatter

Replaces: Black, Flake8, isort, pyupgrade, autoflake, pydocstyle

Core commands:

# Format code (Black-compatible)
uv run --offline ruff format .

# Check for issues
uv run --offline ruff check .

# Auto-fix issues
uv run --offline ruff check --fix .

# Watch mode
uv run --offline ruff check --watch .

Configuration: See ruff.toml for recommended config (Black-compatible + essential rules)

Docs: https://docs.astral.sh/ruff/

Full reference: resources/ruff.md (199 lines)

UV - Fast Package Manager

Replaces: pip, poetry, pyenv, pipx, virtualenv

Speed: 10-100x faster than pip (Rust-based)

Core commands:

# Create project
uv init myproject

# Add dependency
uv add requests

# Run script (auto-installs deps)
uv run python script.py

# Install Python version
uv python install 3.13

PEP 723 pattern (self-contained scripts):

#!/usr/bin/env -S uv run
# /// script
# dependencies = [
#     "typer>=0.9.0",
#     "requests>=2.31.0",
# ]
# ///

import typer
import requests

def main():
    """Script with auto-resolved dependencies."""
    pass

if __name__ == "__main__":
    main()

⚠️ PEP 723 Limitation: Cannot access workspace packages (acf-openai, etc.)

UV docs: "When using inline script metadata, the project's dependencies will be ignored"

Use PEP 723 for:

External/portable scripts (outside .claude/skills/)
Scripts with only PyPI dependencies
Demo/example scripts for distribution

Use workspace scripts for:

Scripts in .claude/skills/ needing shared utilities
Scripts importing acf-openai, workspace members
Internal tooling with code reuse

Workspace script pattern:

#!/usr/bin/env python3
"""Script using workspace packages (requires uv sync)."""

from acf.openai import ExitCode, GitContext, create_agent
import typer

def main():
    """Script with workspace dependencies."""
    context = GitContext.gather_context()
    # ...

if __name__ == "__main__":
    main()

Workspace pattern (monorepo):

project/
├── .venv/                    # Shared virtual environment
├── pyproject.toml            # Root config
├── lib1/
│   └── pyproject.toml        # Workspace member
└── lib2/
    └── pyproject.toml        # Workspace member

Docs: https://docs.astral.sh/uv/

Full reference: resources/uv.md (275 lines)

Quality Gates

Pre-commit checks: ruff, mypy, pytest

Execution order:

Linting (ruff check .)
Type checking (mypy . - if configured)
Tests (pytest)

Evidence format:

✅ Linting: All checks passed (ruff)
✅ Type checking: No issues found (mypy)
✅ Tests: 10 passed in 2.5s (pytest)

Integration: /commit workflow → Step 4 quality gates

Full workflow: resources/quality-gates.md (failure handling, skip conditions, performance notes)

Design Patterns

40 patterns from python-patterns repo (commit 90016f4, 2025-10-17).

Most Common Patterns

Essential 7 (learn these first):

Factory - Object creation without specifying class
Singleton/Borg - Shared state or single instance
Decorator - Dynamic functionality wrapping
Adapter - Interface compatibility
Observer - Event notification
Strategy - Swappable algorithms
Command - Encapsulated requests

Pattern Selection

Creating objects? → Creational

Multiple ways to create? → Factory, Abstract Factory
Complex construction? → Builder
Expensive creation? → Prototype, Pool
Shared state? → Borg

Combining objects? → Structural

Incompatible interfaces? → Adapter
Simplify complex system? → Facade
Add functionality? → Decorator
Control access? → Proxy
Tree hierarchy? → Composite

Object interaction? → Behavioral

Event notification? → Observer, Publish/Subscribe
Swap behavior? → Strategy, State
Request queueing? → Command
Sequential access? → Iterator
Coordinate interactions? → Mediator

Testing? → Testability

Decouple dependencies? → Dependency Injection

Using Patterns

Pattern files: patterns/{category}/{pattern}.py

Each file includes:

Comprehensive docstring (What, Example, Practical Use, References, TL;DR)
Runnable implementation with type hints
Example usage with expected output

Example (Factory pattern):

from patterns.creational.factory import get_localizer

# Create localizers for different languages
english = get_localizer("English")
greek = get_localizer("Greek")

# Same interface, different behavior
print(english.localize("dog"))  # "dog"
print(greek.localize("dog"))    # "σκύλος"

Comprehensive reference: resources/patterns.md (198 lines - all 40 patterns with when-to-use guide)

Detailed catalog: patterns/README.md (166 lines - descriptions, version tracking)

Example Workflows

1. Format Existing Code

# Format with Ruff (Black-compatible)
uv run --offline ruff format .

# Check for issues
uv run --offline ruff check .

# Auto-fix issues
uv run --offline ruff check --fix .

2. Create PEP 723 Script

#!/usr/bin/env -S uv run
# /// script
# dependencies = [
#     "typer>=0.9.0",
# ]
# ///

import typer

app = typer.Typer()

@app.command()
def hello(name: str):
    """Greet someone."""
    print(f"Hello {name}!")

if __name__ == "__main__":
    app()

Run: uv run script.py hello Claude (auto-installs deps)

3. Apply Design Pattern

Scenario: Need event notification system

Pattern: Observer pattern (behavioral/observer.py)

from patterns.behavioral.observer import Subject, Observer

class DataStream(Subject):
    """Observable data source."""
    def __init__(self):
        super().__init__()
        self._data = None

    def update_data(self, data):
        self._data = data
        self.notify(data)  # Notify all observers

class Logger(Observer):
    """Observer that logs changes."""
    def update(self, data):
        print(f"Log: Data changed to {data}")

# Usage
stream = DataStream()
logger = Logger()
stream.attach(logger)
stream.update_data("new value")  # Logger prints: "Log: Data changed to new value"

4. Set Up New Project

# Create project with UV
uv init myproject
cd myproject

# Add dependencies
uv add requests pydantic

# Create recommended Ruff config
cat > ruff.toml << 'EOF'
line-length = 88
target-version = "py313"

[lint]
select = ["E", "F", "I", "UP", "D"]
ignore = ["D203", "D213"]

[lint.pydocstyle]
convention = "google"

[format]
quote-style = "double"
EOF

# Format code
uv run --offline ruff format .

# Check code
uv run --offline ruff check .

Quick Reference

Styleguide: PEP 8 + Black (88) + Ruff + Google docstrings → resources/styleguide.md

Ruff: All-in-one linter/formatter → resources/ruff.md, https://docs.astral.sh/ruff/

UV: Fast package manager → resources/uv.md, https://docs.astral.sh/uv/

Patterns: 40 design patterns → resources/patterns.md (comprehensive), patterns/README.md (catalog)

Pattern files: patterns/{category}/{pattern}.py (creational, structural, behavioral, testability, fundamental, other)

Resources

Internal:

resources/styleguide.md - Researched recommendation with rationale (338 lines)
resources/ruff.md - Linter/formatter quick reference (199 lines)
resources/uv.md - Package manager quick reference (275 lines)
resources/patterns.md - Design patterns guide (198 lines)
patterns/README.md - Pattern catalog with version tracking (166 lines)
patterns/{category}/*.py - 40 pattern implementations
ruff.toml - Recommended Ruff configuration
pyproject.toml - Skill dependencies

External:

PEP 8: https://peps.python.org/pep-0008/
Black: https://black.readthedocs.io/
Google Python Style Guide: https://google.github.io/styleguide/pyguide.html
Ruff: https://docs.astral.sh/ruff/
UV: https://docs.astral.sh/uv/
python-patterns: https://github.com/faif/python-patterns (42.3k stars)
Design Patterns book: "Design Patterns: Elements of Reusable Object-Oriented Software" (Gang of Four)

Integration with Agents

python-pro agent - Advanced Python development agent that leverages this skill

How it works:

Agent provides Sonnet 4.5 optimizations (extended thinking, parallel execution)
Agent focuses on advanced features (async patterns, performance, type system mastery)
Skill provides foundation (styleguide, patterns, tools, testing standards)
Single source of truth: All standard Python guidance in skill, not duplicated in agent

Benefits:

Token efficiency (agent 97 lines, skill 424 lines + resources)
Maintainability (update skill once → agent benefits)
Clear specialization (agent = advanced, skill = foundation)

Integration with Other Skills

Codex (codex-skill): Quick Python questions without workflow overhead

Session Notes (session-notes): Capture styleguide decisions, pattern choices

Thought Capture (thought-capture): Document insights about Python patterns, gotchas

Research Assistant (research): Deep dives into Python libraries, frameworks

Notes

Universal skill: Designed for community sharing, not project-specific

Evidence-based: Styleguide researched from Django, FastAPI, Ruff defaults, Black adoption

Comprehensive patterns: All 40 patterns from python-patterns (not just common 7)

Maintenance: See CLAUDE.md for pattern sync workflow (upstream: python-patterns repo)

Version tracking: Patterns synced from commit 90016f4 (2025-10-17)

python

Install Skill

SKILL.md