agent-skills

Portable, agent-neutral skills for Python packaging and compiled-extension work: choosing a build backend, modernizing packaging metadata, porting C/C++ extension ABIs (stable ABI / abi3, free-threading, PyTorch), building a secure release pipeline, and auditing crypto/FIPS use. A skill is a small folder of Markdown with a defined workflow, on the open Agent Skills standard — so the same files work across Claude Code, Codex, and other coding agents. They are AI-generated but grounded, hand-reviewed by a CPython core developer (how).

Grouped by topic — project bootstrap, then build backends, then packaging metadata, then compiled-extension and ABI ports, then release and auditing:

Status reflects how battle-tested a skill is:

• Stable — applied across many projects; workflow and references verified.
• Beta — built from real, source-verified cases and used on a few; solid but expect rough edges, and check its output.
• Experimental (Exp in the table) — early draft, not yet run end-to-end.

All skills share a common skills/GUARDRAILS.md — operating rules the agent follows unless you say otherwise: use uv + a project .venv (never global installs), don't delete content or commit/push without approval, ask before heavy installs/compiles, and match the project's style.

The skills drive real builds, so the agent needs a working Python build environment: uv for every skill, plus — for the compiled-extension skills — a C/C++ compiler (and CUDA/Fortran toolchains where relevant) and your platform's Python development headers (python3-dev on Debian/Ubuntu, python3-devel on Fedora/RHEL).

This repo is a Claude Code plugin marketplace:

/plugin marketplace add tiran/agent-skills
/plugin install tiran-skills@tiran

New skills and fixes land as commits. To pull them into an existing install:

/plugin marketplace update tiran     # git-pulls this repo
/reload-plugins                      # apply in the current session

This plugin carries no version field, so Claude Code tracks it by commit SHA — every marketplace update that pulls a new commit refreshes the install, with no version bump to remember. If a refresh seems stuck, rm -rf ~/.claude/plugins/cache and re-run the update.

Either install it as a plugin from the plugin browser (/plugins inside Codex — the repo ships a portable plugin.json), or use a skill locally by linking it into a path Codex scans (.agents/skills/ up to the repo root, or ~/.agents/skills/ for all projects):

mkdir -p ~/.agents/skills
ln -s "$PWD/skills/port-to-torch-stable-abi" ~/.agents/skills/

Point the agent at a skill's SKILL.md and have it follow the steps. Nothing here depends on a specific agent framework.

Once installed, just describe the task — the agent matches it to a skill via the descriptions in the table above and follows that SKILL.md. For example:

Which build backend should I use for my Cython + CUDA project?

triggers choose-python-build-backend. Or point an agent straight at a skill file:

Follow skills/port-to-scikit-build-core/SKILL.md to migrate this package's build.

agent-skills/
├── AGENTS.md                 # entry point for agents using skills (CLAUDE.md symlinks to it)
├── CONTRIBUTING.md           # conventions for editing this repo / authoring skills
├── plugin.json               # portable Codex plugin manifest
├── .claude-plugin/           # Claude Code marketplace + plugin metadata
└── skills/
    ├── GUARDRAILS.md         # shared operating rules every skill links to
    └── <skill-name>/
        ├── SKILL.md          # the workflow — the skill's source of truth
        └── reference/        # tables and background, referenced on demand

The skills and their reference material are AI-generated, but grounded — not invented. They are distilled from real project migrations, upstream contributions, the current PyPA and tool documentation, and writing by other packaging practitioners, then cross-checked against those sources and reviewed by hand — informed by two decades of Python experience, including work as a CPython core developer. The recommendations reflect established practice, not just model output. Treat them as a well-sourced starting point, follow the linked authoritative docs when in doubt, and see each skill's Status for how battle-tested it is. The projects they draw on are listed in skills/reference-repos.md.

Improvements to the existing skills — corrections, clearer steps, better references — are welcome. Conventions live in CONTRIBUTING.md; each skill is one directory under skills/<name>/ with a single SKILL.md (the workflow) and supporting material under reference/.

Draft with AI if it helps, but read it and cut it down before you commit — unedited AI text is long, unchecked, and expensive to review.

Apache-2.0.