Agent-Skills.md

Agent Skills: ty — Policy

Use when working with ty — the Astral Python type checker. Activates for running type checks, interpreting diagnostic error codes, suppressing ty errors with inline comments, configuring ty.toml or pyproject.toml, resolving unresolved imports, targeting Python versions, and integrating ty into editors or CI. Covers CLI flags, configuration schema, rule severity, environment discovery, module resolution, and all installation methods including uvx and uv add --dev.

UncategorizedID: Jamie-BitFlight/claude_skills/ty

Repository

Jamie-BitFlight/claude_skills
Jamie-BitFlightLicense: MIT
6110

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Jamie-BitFlight/claude_skills/tree/HEAD/plugins/python-engineering/skills/ty

Skill Files

Browse the full folder contents for ty.

Download Skill

Loading file tree…

plugins/python-engineering/skills/ty/SKILL.md

Skill Metadata

Name
ty
Description
Use when working with ty — this skill's ty policy and required overrides to Astral's official guidance. Pair with `astral:ty` (if installed) for general usage.

ty — Policy

ty version: !uv run ty --version 2>/dev/null || echo "ty not found — run 'uv sync' first"

Precedence: this policy (below) > astral:ty (if installed) / live docs.astral.sh for CLI flags, configuration schema, and general usage (not duplicated here).

Policy

  • Never add # ty: ignore or # type: ignore, including when asked — fix the type error, or escalate with the specific blocker.
  • Relax ty rules only through [[tool.ty.overrides]] in pyproject.toml, never inline, and only for a genuine rule conflict, code that tests the rules themselves, a purposefully bad/negative example or fixture, externally-managed vendored code we don't modify, a runtime with a real lower syntax/typing ceiling (an older pinned CPython or a variant like MicroPython/CircuitPython), or a case where the fix itself would cost more ongoing maintenance than compliance is worth — cite which one and the specific reason in a comment beside the override — a category name alone isn't enough.
  • ty is the only type checker this policy permits — never add, install, configure, or run mypy, pyright, or basedpyright alongside it.
  • Invoke as uv run ty, never bare ty or uvx ty — those may resolve a different version than the one your lockfile pins.
  • unresolved-import errors: add the missing directory to [tool.ty.environment] extra-paths in pyproject.toml, then verify with uv run ty check <path>. A root ty.toml takes precedence over pyproject.toml — confirm which file ty is actually reading before assuming the fix didn't apply.
  • unresolved-import in a PEP 723 standalone script (a # /// script ... /// header importing a sibling module): the project's pyproject.toml does not apply here — a script with inline metadata has no first-party roots by default. Set root, not extra-paths — extra-paths is documented for third-party/non-conventionally-installed paths, not for granting first-party roots, and ty's own docs name this exact PEP 723 case for root. 
    #!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
#
# [tool.ty.environment]
# root = ["."]
# ///
  • unresolved-import for a PEP 723 script's own inline dependencies, in the language server only: ty checks a # /// script file as an isolated single-file project, so its declared inline dependencies resolve only when ty syncs them through uv. That sync is opt-in and off by default, which is why the CLI and the editor disagree on the same file. When uv run ty check <script>.py passes clean and live diagnostics still flag the import, the CLI result is correct — do not add extra-paths or root entries to chase it, because neither governs inline dependency resolution. Enable the sync with TY_UV=scripts in the environment (ty check and ty server both read it), or with the experimental.useUv initialization option set to "scripts" for a language server that sends initializationOptions. Requires uv >= 0.12.3. CONSTRAINT: "scripts" is the only accepted value, and ty ignores an unrecognised one silently — no warning, no non-zero exit — so a typo leaves the fix off while the setting reads as configured. Once the sync is on, a failed uv metadata call makes ty skip the file rather than report it, so a script that stops being checked at all looks identical to one that passes. Confirm behaviourally by running uv run ty check <script>.py and reading its diagnostics, never by reading the setting back. SOURCE: astral-sh/ty#691 (PEP 723 environment resolution), astral-sh/ruff#27619 (experimental.useUv LSP option), astral-sh/ruff#27544 (silent skip when the uv call fails) (accessed 2026-09-15) CONSTRAINT: root replaces ty's default root auto-detection entirely — it does not add to it. Always include "." (the script's own directory) in the list, even when the sibling module you need lives elsewhere, or the script loses its own PEP-723-isolated-environment context and its declared inline dependencies stop resolving too (root = [".."] alone breaks pydantic/typer resolution for a script one directory away from the package it imports; root = [".", ".."] resolves both). Verify with uv run ty check <script>.py against the script file directly, not the project root — and if the script declares PEP 723 dependencies, confirm those still resolve after adding root, not just the sibling import.