ty-skills — Claude Code skill: what it does, how to install
ty-skills guides AI assistants on Python type checking with Astral's ty, fixing diagnostics, and configuring rules in pyproject.toml.
MIT 133 installs ★ 10 updated 2026-01-25
npx skills add jiatastic/open-python-skills --skill ty-skills -a claude-codeWhat ty-skills does
This skill instructs the agent on using Astral's fast Rust-based type checker, ty. It includes reference files covering compiler rules, common diagnostic fixes, and advanced patterns such as protocols, generics, and intersection types.
The skill covers migration steps from mypy or pyright, editor setup guides, and configuration options inside pyproject.toml. It also explains how to suppress individual diagnostics with comments like # type: ignore[incompatible-assignment].
This repository only provides documentation and instructions for the agent; running actual checks requires installing ty on your machine via uv tool install ty or pip install ty.
What it helps with
- Configure project type checking rules in
pyproject.toml - Resolve
invalid-argument-typeand unbound attribute errors reported by ty - Migrate existing Python codebases from mypy or pyright to ty
- Define intersection types and protocols in Python annotations
Example prompts for the agent
- Help me configure [tool.ty.rules] in pyproject.toml and set unresolved references to error.
- Fix this invalid-argument-type diagnostic reported by ty check in src/service.py.
- How do I write an intersection type in Python using ty?
How to install ty-skills
1Skills CLI (Vercel)
npx skills add jiatastic/open-python-skills --skill ty-skills -a claude-code2Manually: put the files in place
~/.claude/skills/ty-skills/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ty-skills/
1Skills CLI (Vercel)
npx skills add jiatastic/open-python-skills --skill ty-skills -a codex2Manually: put the files in place
.agents/skills/ty-skills/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jiatastic/open-python-skills --skill ty-skills -a cursor2Manually: put the files in place
.cursor/skills/ty-skills/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jiatastic/open-python-skills skills/ty-skills2Manually: put the files in place
.github/skills/ty-skills/SKILL.md1Skills CLI (Vercel)
npx skills add jiatastic/open-python-skills --skill ty-skills -a gemini-cli2Platform CLI
gemini skills install https://github.com/jiatastic/open-python-skills --path skills/ty-skillsManually: put the files in place
.devin/skills/ty-skills/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add jiatastic/open-python-skills --skill ty-skills -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ty-skills
How do I install ty-skills in Claude Code?
Run npx skills add jiatastic/open-python-skills --skill ty-skills -a claude-code in your terminal.
What is ty-skills?
It is a skill that teaches coding assistants how to configure and run Astral's ty type checker, resolve diagnostic errors, and handle advanced typing patterns.
Does ty-skills install the ty binary automatically?
No, the skill only adds contextual knowledge to the assistant. You must install the ty CLI tool separately using uv or pip.
Source text
SKILL.md · MIT
---
name: ty-skills
description: >
Python type checking expertise using ty - the extremely fast type checker by Astral.
Use when: (1) Adding type annotations to Python code, (2) Fixing type errors reported by ty,
(3) Migrating from mypy/pyright to ty, (4) Configuring ty for projects,
(5) Understanding advanced type patterns (generics, protocols, intersection types),
(6) Setting up ty in editors (VS Code, Cursor, Neovim, PyCharm).
---
# ty-skills
Master Python type checking with [ty](https://docs.astral.sh/ty/) - the extremely fast type checker written in Rust by Astral (creators of uv and Ruff).
## When to Use This Skill
- Adding type annotations to Python code
- Fixing type errors and diagnostics from ty
- Configuring ty rules and severity levels
- Migrating from mypy or pyright to ty
- Understanding advanced type patterns (intersection types, protocols, generics)
- Setting up ty language server in your editor
## Quick Start
```bash
# Install
uv tool install ty
# or: pip install ty
# Check current directory
ty check
# Check specific files
ty check src/
# Full diagnostics
ty check --output-format full
```
## Configuration
Configure via `pyproject.toml`:
```toml
[tool.ty.environment]
python-version = "3.12"
python = "./.venv"
python-platform = "linux"
root = ["./src"]
extra-paths = ["./typings"]
[tool.ty.rules]
# error: fail CI, warn: report, ignore: disable
possibly-unresolved-reference = "error"
invalid-argument-type = "error"
division-by-zero = "warn"
unused-ignore-comment = "warn"
[tool.ty.src]
include = ["src", "tests"]
exclude = ["src/migrations/"]
# Per-file overrides
[[tool.ty.overrides]]
include = ["tests/**"]
[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"
```
## Rules Quick Reference
| Rule | Default | Description |
|------|---------|-------------|
| `possibly-unresolved-reference` | error | Variable might not be defined |
| `invalid-argument-type` | error | Argument type mismatch |
| `incompatible-assignment` | error | Assigned value incompatible |
| `missing-argument` | error | Required argument missing |
| `unsupported-operator` | error | Operator not supported for types |
| `invalid-return-type` | error | Return type mismatch |
| `division-by-zero` | warn | Potential division by zero |
| `unused-ignore-comment` | warn | Suppression not needed |
| `redundant-cast` | warn | Cast has no effect |
| `possibly-unbound-attribute` | warn | Attribute might not exist |
| `index-out-of-bounds` | warn | Index might be out of range |
## Intersection Types (ty Exclusive)
ty has first-class intersection type support:
```python
def output_as_json(obj: Serializable) -> str:
if isinstance(obj, Versioned):
reveal_type(obj) # reveals: Serializable & Versioned
return str({
"data": obj.serialize_json(), # From Serializable
"version": obj.version # From Versioned
})
return obj.serialize_json()
```
## Suppression Comments
```python
# Suppress single rule
x: int = "hello" # type: ignore[incompatible-assignment]
# Suppress multiple
y = risky() # type: ignore[possibly-unresolved-reference, invalid-argument-type]
```
## Reference Documents
For detailed information, see:
| Document | Content |
|----------|---------|
| `references/ty_rules_reference.md` | All rules with examples and fixes |
| `references/typing_cheatsheet.md` | Python typing module quick reference |
| `references/advanced_patterns.md` | Protocols, generics, type guards, variance |
| `references/migration_guide.md` | mypy/pyright → ty migration |
| `references/common_errors.md` | Error solutions with examples |
| `references/editor_setup/` | VS Code, Cursor, Neovim setup |
## Resources
- [ty Documentation](https://docs.astral.sh/ty/)
- [ty Playground](https://play.astral.sh/ty)
- [ty GitHub](https://github.com/astral-sh/ty)
© jiatastic · MIT · jiatastic/open-python-skills