Agent-Skills.md

Agent Skills: Python Tooling

Use when working with Python tooling — uv package management, Hatchling build backend, ty or mypy type checker configuration, ruff linting, pre-commit hook setup, TOML read-write with tomlkit or tomllib, or PyPI packaging and release workflows. Routes to standalone specialist skills for deep dives on any single tool.

UncategorizedID: Jamie-BitFlight/claude_skills/python3-tools

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/python3-tools

Skill Files

Browse the full folder contents for python3-tools.

Download Skill

Loading file tree…

plugins/python-engineering/skills/python3-tools/SKILL.md

Skill Metadata

Name
python3-tools
Description
Use when working with Python tooling — uv package management, Hatchling build backend, ty or mypy type checker configuration, ruff linting, pre-commit hook setup, TOML read-write with tomlkit or tomllib, or PyPI packaging and release workflows. Routes to standalone specialist skills for deep dives on any single tool.

Python Tooling

Consult python3-core for standing defaults.

uv Package Management

  • uv add for dependencies (not uv pip install)
  • uv run for execution (not source .venv/bin/activate)
  • uv sync --frozen for CI; uv sync --locked to detect stale lockfiles
  • PEP 723 shebang: #!/usr/bin/env -S uv --quiet run --active --script
  • uv venv --clear to overwrite existing environments (since 0.10.0)

Type Checker Detection

Check .pre-commit-config.yaml → CI config → pyproject.toml:

  • Default for new work: ty (Astral)
  • Project runs mypy: respect mypy.ini / [tool.mypy]; do not force ty
  • Project runs pyright/basedpyright: respect that; do not force ty
  • Do NOT infer active checker from presence of [tool.mypy] alone (may be stub config)

Build Backend

Hatchling preferred:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]

Pre-commit

Detect installed tool: read .git/hooks/pre-commit line 2 to identify pre-commit vs prek. Both use the same config file.

TOML Editing

  • tomlkit for read/write (preserves formatting) — open in text mode
  • tomllib (stdlib) for read-only — tomllib.load() requires binary mode ("rb"), tomllib.loads() takes a string

PyPI Packaging

# pyproject.toml
[project]
name = "my-package"
version = "0.1.0"
requires-python = ">=3.11"
classifiers = ["Typing :: Typed"]

[project.scripts]
my-cli = "my_package.cli:app"

Standalone Tool Skills

Load these skills when the task is focused entirely on one tool:

  • Load python-engineering:uv when the task involves uv commands, lockfiles, PEP 723 scripts, workspace configuration, Python version management, CI/CD integration, Docker setup with uv, or migration from pip/poetry/pyenv.
  • Load python-engineering:ty when the task involves running ty type checks, configuring ty.toml or [tool.ty], suppressing diagnostics, interpreting ty error codes, ty editor integration, or migrating from mypy/pyright to ty.
  • Load python-engineering:hatchling when the task involves Hatchling build hooks, custom builders, wheel/sdist configuration, editable installs, VCS version sources, PEP 517/518/621/660 compliance, or setuptools migration.
  • Load python-engineering:toml-python when the task requires advanced TOML manipulation: comment-preserving read-modify-write, atomic config updates, tomlkit API patterns, or XDG config file management.
  • Load python-engineering:pre-commit when the task requires configuring hook stages, writing .pre-commit-hooks.yaml definitions, implementing prepare-commit-msg hooks, or distributing a tool as a pre-commit hook.
  • Load python-engineering:pypi-readme-creator when the task involves creating or validating a PyPI README, choosing between Markdown and RST formats, configuring readme in pyproject.toml, or running twine check.

References

  • references/tooling-defaults.md — full tooling reference
  • references/compatibility-lanes.md — version compatibility