typing skill improvements

docs/skills/python-typing/SKILL.md

@@ -24,6 +24,7 @@ Use this skill to enforce a latest-syntax-first typing standard grounded in curr
 Load references only when needed:
 - Source map and standards links: [typing source map](./references/index.md)
 - Practical review workflow and quality gates: [typing review workflow](./references/review-workflow.md)
+- Astral ty adoption and operation guidance: [Astral ty usage reference](./references/astral-ty.md)
 
 ## When to Use
 
@@ -44,19 +45,22 @@ Load references only when needed:
 
 - Baseline and compatibility checks: [typing source map](./references/index.md)
 - Exact modernization sequence and branching logic: [typing review workflow](./references/review-workflow.md)
+- Integrating or tuning Astral ty: [Astral ty usage reference](./references/astral-ty.md)
 - Need official rationale for a specific feature: [typing source map](./references/index.md)
 
 ## Load Order
 
 1. Start with [typing source map](./references/index.md) for authoritative links.
 2. Load [typing review workflow](./references/review-workflow.md) to execute the review.
-3. Return to source links for any feature-level recommendation included in the final output.
+3. Load [Astral ty usage reference](./references/astral-ty.md) 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. Do not load additional docs unless a project-specific edge case requires it.
+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
 

docs/skills/python-typing/references/astral-ty.md

@@ -0,0 +1,59 @@
+# Astral ty Usage Reference
+
+Use this page when you want to run or adopt [ty](https://docs.astral.sh/ty/), Astral's Python type checker and language server, in a typing-focused workflow.
+
+## Quick Start
+
+- Run a one-off check without installing globally: `uvx ty check`
+- Run checks in the current project: `ty check`
+- Explore behavior quickly in the [ty playground](https://play.ty.dev/)
+
+Primary docs:
+
+- [Getting started](https://docs.astral.sh/ty/#getting-started)
+- [Installation](https://docs.astral.sh/ty/installation/)
+- [Type checking](https://docs.astral.sh/ty/type-checking/)
+- [CLI reference](https://docs.astral.sh/ty/reference/cli/)
+
+## Editor Integration
+
+Use ty as a language server in supported editors.
+
+- [Editor integration overview](https://docs.astral.sh/ty/editors/)
+- [VS Code setup](https://docs.astral.sh/ty/editors/#vs-code)
+- [Language server capabilities](https://docs.astral.sh/ty/features/language-server/)
+- [Editor settings reference](https://docs.astral.sh/ty/reference/editor-settings/)
+
+## Configuration Surface
+
+Start from project defaults, then add targeted overrides only where needed.
+
+- [Configuration guide](https://docs.astral.sh/ty/configuration/)
+- [Configuration reference](https://docs.astral.sh/ty/reference/configuration/)
+- [Python version handling](https://docs.astral.sh/ty/python-version/)
+- [Module discovery](https://docs.astral.sh/ty/modules/)
+- [File exclusions](https://docs.astral.sh/ty/exclusions/)
+
+## Rule And Suppression Controls
+
+Use this set when tuning signal-to-noise in large or partially typed codebases.
+
+- [Rules overview](https://docs.astral.sh/ty/rules/)
+- [Rules reference](https://docs.astral.sh/ty/reference/rules/)
+- [Suppression comments and directives](https://docs.astral.sh/ty/suppression/)
+- [Diagnostics feature docs](https://docs.astral.sh/ty/features/diagnostics/)
+
+## Migration Notes
+
+For teams moving from existing type checkers, use Astral's migration guidance first.
+
+- [Coming from mypy or pyright](https://docs.astral.sh/ty/coming-from-mypy-or-pyright/)
+- [Typing FAQ](https://docs.astral.sh/ty/reference/typing-faq)
+
+## Suggested Review Flow With ty
+
+1. Confirm Python baseline and project targets.
+2. Run `uvx ty check` for an initial signal pass.
+3. Configure version/module/discovery settings as needed.
+4. Triage diagnostics and tune rules or suppressions deliberately.
+5. Re-run checks and keep modernization changes behavior-preserving unless explicitly requested.

docs/skills/python-typing/references/index.md

@@ -8,6 +8,11 @@ Use this page as the canonical source index when making typing modernization rec
 - [Typing specification (typing.python.org)](https://typing.python.org/)
 - [Built-in types and generic aliases](https://docs.python.org/3/library/stdtypes.html)
 
+## Tooling References
+
+- [Astral ty documentation](https://docs.astral.sh/ty/)
+- [Astral ty usage reference (this skill)](./astral-ty.md)
+
 ## Modernization PEPs
 
 - [PEP 585: Type Hinting Generics In Standard Collections](https://peps.python.org/pep-0585/)