python-skill

A compact Python skill catalogue for Codex, shaped to help with real Python work without drowning out the work itself.

This repository carries an advanced Python skill set modelled on the rust-skill catalogue: a single router, a handful of focused language skills, a verification selector with three deep dives, and a quality-tools skill for the scanners and profilers beyond unit testing and type-checking.

• Small default load: One router and a small set of first-class skills; references carry the longer comparison material.
• Python-specific judgement: The catalogue focuses on typing decisions, errors and logging, abstractions, iterators and generators, data shapes, concurrency, testing, verification, and quality tooling.
• Clear routing: python-router directs to the smallest useful skill instead of loading half the catalogue at once.
• Practical tone: The skills aim to sound like a helpful technical lead, not a tutorial.

mkdir -p ~/.codex/skills
cp -a skills/* ~/.codex/skills/

Use $python-router to route this Python task, then help me design the
exception hierarchy for a payments service.

When the pressure point is already known, call the skill directly:

Use $python-errors-and-logging to review this handler's `except` clauses
for a publishable library.

• One router, focused language skills, and dedicated domain and quality skills.
• Short SKILL.md files, with references for the longer comparison material.
• Coverage for typing (PEP 612, PEP 695, PEP 696, PEP 698, PEP 742), exceptions and logging (Ruff TRY/BLE/EM/LOG/N818/PERF203/B017), decorators and descriptors, context-manager extraction, iterator refactors, msgspec-shaped data, dataclass and TypedDict choices, and PEP 734 subinterpreters.
• Verification skills covering selection plus deep dives for hypothesis, crosshair, and mutmut.
• Quality-tool skill for deadcode, pyscn, and Pyinstrument.
• Skylos dead-code management: safe deletion, implicit runtime callers, precise entrypoint exceptions, and merge-aware configuration contracts.
• Ruff 0.16 skill covering the 413-rule default set, ruff: ignore suppression comments, Markdown formatting, and the documented settings, CLI, and rule deltas since 0.14.0 — the material most models predate.

• Users' guide — installation, invocation, routing, and when to reach for the verification or quality-tool skills.
• Developers' guide — working on this repository: prerequisites, the Makefile gates, and what the test suite covers.
• Skill catalogue status — what is active and what is research input.
• Initial-skill execplan — design, rationale, and validation history for the catalogue.
• ADR 0001 — why the Ruff skill is version-pinned and where its routing boundary sits.
• Python router — the main entry point.
• Types and APIs — generics, TypeVar, ParamSpec, TypeIs, overloads, typed kwargs.
• Skylos — dead-code triage, Protocol and callback false positives, narrow configuration, and regression evidence.
• Ruff 0.16 — default rule set, suppression comments, Markdown formatting, settings and rule deltas.

The catalogue combines Markdown content with a small Python test suite. Run the gates through the Makefile rather than invoking the tools directly:

make test also needs mdtablefix 0.6.1 or later on PATH, because the end-to-end formatting tests run it for real; make test and make typecheck require uv; the dev dependency group in pyproject.toml supplies pytest, cmd-mox, mypy, Hypothesis, PyYAML, skills-ref, and yamllint. The Makefile tests stub the external Markdown tools with cmd-mox, except mdtablefix, which the end-to-end tests run. The developers' guide covers the gates in full, and scripting standards gives the conventions any new Python must follow.

This catalogue draws on the Python rules and guides shipped with agent-template-python (exceptions and logging, typing, context managers, generators, return discipline, pyproject layout) and on the structure established by the rust-skill catalogue. The verification skills lean on the documentation and source of Hypothesis, CrossHair, and mutmut; the quality-tool skill leans on deadcode, pyscn, and Pyinstrument. The Ruff skill draws on Ruff. The Skylos skill draws on Skylos documentation and pinned source, together with a maintainer-supplied dead-code triage case.

ISC — see LICENSE for details.

Contributions are welcome. Read AGENTS.md before changing tracked files: it lists the commit gates and the rules for changes under skills/. Keep new material under skills/, prefer short first-class skills with references for longer detail, and update docs/skill-catalogue-status.md when adding or retiring a skill.