Python Type Safety

A comprehensive guide to Python's type system that goes beyond basic annotations. Covers generics, protocols, and type narrowing with practical patterns you'll actually use. The generic repository examples and protocol definitions are solid starting points for building type-safe APIs. Works well with mypy strict mode and pyright for catching errors before runtime. The Result class and structural typing patterns are especially useful for larger codebases where type safety becomes critical for maintenance.

install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.: 7
skills.sh installs: 13.2K
GitHub stars: 42.4K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add wshobson/agents --skill python-type-safety --agent claude-code

Installs into .claude/skills of the current project.

Files

Python Type Safety

Leverage Python's type system to catch errors at static analysis time. Type annotations serve as enforced documentation that tooling validates automatically.

When to Use This Skill

Adding type hints to existing code
Creating generic, reusable classes
Defining structural interfaces with protocols
Configuring mypy or pyright for strict checking
Understanding type narrowing and guards
Building type-safe APIs and libraries

Core Concepts

1. Type Annotations

Declare expected types for function parameters, return values, and variables.

2. Generics

Write reusable code that preserves type information across different types.

3. Protocols

Define structural interfaces without inheritance (duck typing with type safety).

4. Type Narrowing

Use guards and conditionals to narrow types within code blocks.

Quick Start

def get_user(user_id: str) -> User | None:
    """Return type makes 'might not exist' explicit."""
    ...

# Type checker enforces handling None case
user = get_user("123")
if user is None:
    raise UserNotFoundError("123")
print(user.name)  # Type checker knows user is User here

SKILL.md on GitHub