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 = ["."]
# ///
    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.