Skip to content

skillCode qualitypython

Python Type Hints

Adds and tightens Python type hints, then runs mypy or pyright until clean without blanket ignores. Use it on untyped or loosely typed modules.

npx workspacetemplates add python-type-hints --tool claude-code

Writes 1 file to .claude/skills/python-type-hints/

.claude/skills/python-type-hints/SKILL.md28 lines · 1.6 KBFile
---
name: python-type-hints
description: Adds and tightens Python type hints, then runs mypy or pyright until clean without blanket ignores. Use it on untyped or loosely typed modules.
---

# Python type hints

Types are documentation the machine checks. Make them accurate before making them green.

## Steps

1. Detect the checker: look for `mypy.ini`, `[tool.mypy]` or `[tool.pyright]` in `pyproject.toml`, or `pyrightconfig.json`. Run it first and record the baseline error count.
2. Work one module at a time, starting with the leaves that others import.
3. Annotate every public function: parameters, return type, and `-> None` where it returns nothing. Prefer `list[str]` and `X | None` over `typing.List` and `Optional` on Python 3.10+.
4. Replace loose dicts with `TypedDict`, `dataclass` or `NamedTuple` when the keys are fixed. Use `Protocol` for duck-typed arguments and `TypeVar` or `ParamSpec` for decorators.
5. Prefer `Sequence` and `Mapping` for read-only parameters, concrete types for returns.
6. Run the checker after each module and fix errors by correcting the code or the type.

## Rules

- Never add `# type: ignore` without an error code and a one-line reason, for example `# type: ignore[arg-type]  # lib stubs wrong`.
- Do not use `Any` to silence an error. Use `object`, a union or a generic first.
- Never change runtime behavior to satisfy the checker unless it exposes a real bug, and say so when it does.
- Use `cast` sparingly and only after an `isinstance` check you can point to.

## Report

Baseline vs final error count, modules annotated, each remaining ignore with its reason, and real bugs the checker revealed.

What it does

Annotating a module with Any everywhere produces a green checker and no safety. This skill asks for real types: precise parameters, return types, generics, TypedDicts and Protocols, checked with the type checker your project already configures.

When the checker complains, the agent fixes the cause. A narrow, commented ignore is the last resort, and every one is listed in the final report so you can review it.

Example

you › Add type hints to the billing package and get mypy clean.

agent › Annotated 9 modules in billing/. mypy errors went from 74 to 0. Introduced Invoice as a TypedDict and a PaymentGateway Protocol. Two ignores remain, both with codes: a stripe stub gap in gateway.py:31 and a dynamic attribute in plans.py:88. mypy also exposed a real bug: refund() could return None when the invoice was missing.

Questions

Does it work with pyright instead of mypy?
Yes. It uses whichever checker your configuration names, and falls back to asking you if it finds neither.
Why does it avoid Any so strictly?
Any switches checking off for everything it touches. The skill prefers unions, protocols and generics so the checker keeps catching mistakes downstream.
  • API Deprecation Handling

    SkillCode quality

    Free
  • Code Duplication Removal

    SkillCode quality

    Free
  • Code Smell Detection

    SkillCode quality

    Free
  • Concurrency Bug Analysis

    SkillCode quality

    Free