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

Input	Why
Package name	PyPI name availability
License	MIT, Apache-2.0, proprietary
Python floor	`requires-python` (3.14 vs 3.13)
Optional extras	`dev`, `gpu` dependency groups
Publish target	PyPI, private index, Artifactory

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

src layout - import package from src/ not repo root on sys.path.
No secrets in pyproject - tokens only in CI secrets.
Pin build backend - hatchling or setuptools explicitly.
CHANGELOG entry per release - Keep a Changelog format.
Tag vX.Y.Z triggers publish - not every main commit.
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

uv publish or twine?

uv publish when available in pinned uv; otherwise twine upload - skill documents both.

Monorepo multiple packages?

One pyproject.toml per package or workspace uv config - document chosen layout in README.

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+.

Input

Why

Package name

PyPI name availability

License

MIT, Apache-2.0, proprietary

Python floor

requires-python (3.14 vs 3.13)

Optional extras

dev, gpu dependency groups

Publish target

PyPI, private index, Artifactory

Guardrails

src layout - import package from src/ not repo root on sys.path.

No secrets in pyproject - tokens only in CI secrets.

Pin build backend - hatchling or setuptools explicitly.

CHANGELOG entry per release - Keep a Changelog format.

Tag vX.Y.Z triggers publish - not every main commit.

Test on TestPyPI before prod index first time.

[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"]

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+.

Packaging & Publishing Skill

Search Documentation

Packaging & Publishing Skill