Packaging & Publishing Skill

Project scaffolding and PyPI releases - an Agent Skill for Python 3.14 and uv 0.6+.

What This Skill Does

Creates publishable library layout: src/<package>/, pyproject.toml (PEP 621), README.md, LICENSE, CHANGELOG.md, GitHub Actions release.yml, TestPyPI dry-run steps, and version bump policy.

When to Invoke

• Extracting shared utils from monorepo into library
• First open-source release of internal package
• Modernizing setup.py legacy project to pyproject
• Reviewing PR that breaks sdist/wheel metadata

Inputs

Outputs

• src/<name>/__init__.py with __version__
• [project.scripts] if CLI entrypoint needed
• uv build / python -m build verification block
• Trusted publisher OIDC workflow or token via GitHub secrets
• twine check dist/* in CI

Guardrails

1. src layout - import package from src/ not repo root on sys.path.
2. No secrets in pyproject - tokens only in CI secrets.
3. Pin build backend - hatchling or setuptools explicitly.
4. CHANGELOG entry per release - Keep a Changelog format.
5. Tag vX.Y.Z triggers publish - not every main commit.
6. Test on TestPyPI before prod index first time.

Recipe

uv sync --all-extras
uv run ruff check .
uv run pytest -q
uv build
uv run twine check dist/*
# CI: publish on tag after trusted publisher auth

Working Example (pyproject fragment)

[project]
name = "acme-utils"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = []
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.hatch.build.targets.wheel]
packages = ["src/acme_utils"]

FAQs

Related

• Packaging & Publishing - human guide
• pyproject.toml Explained - metadata
• uv - The Fast Toolchain - tooling
• Python Best-Practices Skill - code quality

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1z22203x1v1t1v1z1t20