Type-Hinting Skill

Adding and tightening type annotations - an Agent Skill for Python 3.14 static typing.

What This Skill Does

Reviews modules and adds types: function signatures, TypedDict, Protocol, TypeVar bounds, assert isinstance narrowing, fixes Any leakage, configures mypy or pyright in pyproject.toml, and enables CI gate on changed paths.

When to Invoke

• New package before first release
• PR introducing Any or untyped public API
• Gradual typing milestone in brownfield service
• Preparing library for PyPI consumers

Inputs

Outputs

• Annotated public functions and class attributes
• pyproject.toml [tool.mypy] or [tool.pyright]
• TYPE_CHECKING imports for circular deps
• # type: ignore audit with ticket refs only when unavoidable
• uv run mypy src/package clean on scope

Guardrails

1. Public API fully typed before internal helpers.
2. No untyped defs in new code - def foo(x: int) -> str.
3. Prefer Protocol over ABC for structural typing.
4. Do not silence with bare ignore - narrow with type: ignore[arg-type] + comment.
5. Run checker in CI on diff paths - expand scope over sprints.
6. Match runtime validation - Pydantic models align with TypedDict where shared.

Recipe

uv sync --extra dev
uv run mypy src/myservice
uv run pyright src/myservice  # if pyright is standard
uv run pytest -q

Working Example

from collections.abc import Sequence
from typing import Protocol
 
 
class SupportsClose(Protocol):
    def close(self) -> None: ...
 
 
def shutdown_all(resources: Sequence[SupportsClose]) -> None:
    for r in resources:
        r.close()

FAQs

Related

• Type Hints Basics - fundamentals
• mypy and pyright Setup - config
• Gradual Typing Strategy - rollout
• Protocols and Structural Typing - patterns

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.