prompts/docs/skills/python-typing/SKILL.md

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
python-typing	Reference-first skill for reviewing and modernizing Python typing to the newest supported best practices. Use when auditing annotations, replacing legacy typing syntax, and enforcing latest-syntax-first conventions.	Which files or package should be reviewed, and what Python baseline must be preserved?	id version tags capabilities depends_on python-typing 1.0.0 python typing type-hints pep-695 modernization static-analysis resource://skills/python-typing/document

Modern Python Typing Review Reference

Use this skill to enforce a latest-syntax-first typing standard grounded in current Python language guidance.

Load references only when needed:

• Source map and standards links: typing source map
• Practical review workflow and quality gates: typing review workflow
• Astral ty adoption and operation guidance: Astral ty usage reference

When to Use

• A codebase still uses legacy typing patterns and should be updated to modern syntax.
• You need a repeatable process for type-focused code review across a package or module.
• You want references to official Python docs and PEPs attached to recommendations.
• You need to decide whether a modern feature is allowed under the project Python version.

How To Use This Skill

1. Confirm the effective Python baseline from project config (for example pyproject.toml and lint target version).
2. Scan target files for legacy patterns and prioritize newest canonical syntax first.
3. Apply modern typing upgrades aggressively, keeping runtime behavior stable unless explicitly requested otherwise.
4. Validate with project lint and diagnostics.
5. Report what changed and list only hard-blocker deferrals (for example incompatible Python baseline).

Intent Router

• Baseline and compatibility checks: typing source map
• Exact modernization sequence and branching logic: typing review workflow
• Integrating or tuning Astral ty: Astral ty usage reference
• Need official rationale for a specific feature: typing source map

Load Order

1. Start with typing source map for authoritative links.
2. Load typing review workflow to execute the review.
3. Load Astral ty usage reference when the workflow includes ty setup, configuration, migration, or editor integration.
4. Return to source links for any feature-level recommendation included in the final output.

Load Budget

1. Default: load one reference (index.md) for lightweight guidance.
2. Standard review: load two references (index.md and review-workflow.md).
3. Add astral-ty.md only when ty is in scope.
4. Do not load additional docs unless a project-specific edge case requires it.

Decision Baseline

Use these defaults unless a hard compatibility constraint prevents them:

1. Prefer built-in generics (list[str], dict[str, int]) over typing.List and typing.Dict.
2. Prefer X | Y over typing.Optional[X] or typing.Union[X, Y].
3. Prefer PEP 695 generics (class Box[T], def fn[T](...)) for Python 3.12+ codebases and use them by default.
4. Prefer typing.Self for fluent instance/class method return typing.
5. Use typing.Literal when a finite value set is the real contract.
6. Remove legacy typing aliases and module-level TypeVar declarations when PEP 695 can replace them.
7. Keep runtime behavior unchanged unless the task explicitly requests behavior refactors.

Completion Checks

1. Modern syntax aligns with the project Python baseline.
2. Linting and diagnostics are clean for edited files.
3. Public APIs are unchanged unless explicitly requested.
4. Feature-level recommendations include source links.
5. Any deferral is backed by a specific hard constraint (for example Python version floor).

Output Contract

Return:

1. Files reviewed and files changed.
2. Applied typing upgrades with brief rationale.
3. Deferred upgrades only when blocked by explicit hard constraints.
4. Validation results (lint/tests/diagnostics).
5. References consulted and discovery path used.