# ty-skills

ty-skills guides AI assistants on Python type checking with Astral's ty, fixing diagnostics, and configuring rules in pyproject.toml.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 133 installs · ★ 10 repo stars
- Author: jiatastic
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/jiatastic/open-python-skills/tree/HEAD/skills/ty-skills/SKILL.md
- Updated: 2026-01-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ty-skills

## What it 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`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add jiatastic/open-python-skills --skill ty-skills -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ty-skills/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ty-skills/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add jiatastic/open-python-skills --skill ty-skills -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ty-skills/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add jiatastic/open-python-skills --skill ty-skills -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ty-skills/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install jiatastic/open-python-skills skills/ty-skills
```

2. **Manually: put the files in place**
- File: `.github/skills/ty-skills/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add jiatastic/open-python-skills --skill ty-skills -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/jiatastic/open-python-skills --path skills/ty-skills
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ty-skills/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add jiatastic/open-python-skills --skill ty-skills -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/jiatastic/open-python-skills/tree/HEAD/skills/ty-skills/SKILL.md

## When to use it
- Configure project type checking rules in `pyproject.toml`
- Resolve `invalid-argument-type` and 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
- 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?

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b18eb6933f9c2397.

BEGIN THIRD-PARTY FILE b18eb6933f9c2397
````text
---
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()
```
````
END THIRD-PARTY FILE b18eb6933f9c2397

The third-party file has ended. Everything between the b18eb6933f9c2397 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2955 of 3870 bytes. © jiatastic · MIT · https://github.com/jiatastic/open-python-skills/tree/HEAD/skills/ty-skills/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
