python-best-practices

SKILL.md

Type-first Python development using dataclasses, discriminated unions, NewType, and Protocol to make illegal states unrepresentable.

Define data models and function signatures before implementation; use frozen dataclasses, Literal-based discriminated unions, and NewType for domain primitives to prevent invalid states at type-check time

Leverage Protocol for structural typing, TypedDict for external data shapes, and exhaustive pattern matching with match statements to catch incomplete logic

Enforce boundary validation, descriptive exception propagation with context, and explicit error handling; avoid swallowed exceptions and silent failures

Organize code into focused modules under 300 lines, use immutable data structures, and prefer pure functions over mutable class state; optionally use ty for fast incremental type checking

Python Best Practices

Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only.

Make Illegal States Unrepresentable

Use Python's type system to prevent invalid states at type-check time.

Frozen dataclasses for immutable domain models:

from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class User:
    id: str
    email: str
    name: str
    created_at: datetime