Python PyPI Package Builder
Create, scaffold, or publish a Python package to PyPI. Also: set up pyproject.toml, CI, linting, versioning.
When NOT to use
- Need to fix a failing import or choose a library for a job (plotting/serving) — use
python-stack-env.
- Building a one-off script or ML experiment package — use
iterate-ml-experiment § 0.5 scaffold; this skill is for publishable libraries.
- Project is not Python — this skill only handles
pyproject.toml Python packaging.
Decision chain
Load the referenced file at each step before proceeding.
1 — Package type
| Type |
Entry point |
Patterns |
| Utility library |
Import API |
references/library-patterns.md |
| API client / SDK |
Import API |
references/library-patterns.md, references/architecture-patterns.md |
| CLI tool |
[project.scripts] |
references/library-patterns.md |
| Framework plugin |
[project.entry-points] |
references/library-patterns.md |
| Mixed |
primary type + secondary |
references/library-patterns.md |
2 — Folder layout
| Situation |
Layout |
| New project, unknown size |
src/ layout (safest default) |
| Single-purpose, 1–4 modules |
Flat |
| Large, many contributors |
src/ |
| Multiple packages in one repo |
Namespace/monorepo |
Templates: references/structure-templates.md.
3 — Build backend
| Condition |
Backend |
Config template |
| C/Cython extensions OR git-tag versioning |
setuptools + setuptools_scm |
references/pyproject-toml.md |
| All-in-one deps + build + publish |
poetry (v2+) |
references/pyproject-toml.md |
| Minimal config, pure Python |
flit |
references/pyproject-toml.md |
| Modern, fast, pure Python |
hatchling |
references/pyproject-toml.md |
Backend comparison, naming rules, PyPA concepts: references/pyproject-toml.md.
4 — Config + publish
Scaffold script: python skills/python-pypi-package-builder/scripts/scaffold.py --name your-package-name.
references/pyproject-toml.md — all four backend templates, py.typed, tool configsreferences/ci-publishing.md — Trusted Publishing, TestPyPI, CHANGELOG, release checklistreferences/versioning-strategy.md — PEP 440, semver, setuptools_scmreferences/testing-quality.md — ruff/mypy/pre-commitreferences/release-governance.md — branch protection, OIDC, tag validationreferences/tooling-ruff.md — Ruff-only lint/formatreferences/community-docs.md — README, CONTRIBUTING, docstrings
Two inline rules:
setuptools_scm CI: fetch-depth: 0 in every checkout (else version silently falls back to 0.0.0+dev).- Library deps: prefer
"httpx>=0.24" (minimum). Never pin == or ~= in a library's `[project] dependencies.
Stop conditions
- Don't infer the package type. Ask the user if unclear.
- Don't skip TestPyDI for first release.
- Don't publish without CI (Trusted Publishing recommended).
Completion criteria
Related skills
python-stack-env — manager detection and env setup before packaging.python-api — verify signatures after scaffold.
1---2name: python-pypi-package-builder3description: Use when building, testing, linting, versioning, or publishing a production-grade Python library to PyPI.4---56# Python PyPI Package Builder78Create, scaffold, or publish a Python package to PyPI. Also: set up `pyproject.toml`, CI, linting, versioning.910## When NOT to use1112- Need to fix a failing import or choose a library for a job (plotting/serving) — use `python-stack-env`.13- Building a one-off script or ML experiment package — use `iterate-ml-experiment` § 0.5 scaffold; this skill is for publishable libraries.14- Project is not Python — this skill only handles `pyproject.toml` Python packaging.1516## Decision chain1718Load the referenced file at each step before proceeding.1920### 1 — Package type2122| Type | Entry point | Patterns |23|---|---|---|24| Utility library | Import API | `references/library-patterns.md` |25| API client / SDK | Import API | `references/library-patterns.md`, `references/architecture-patterns.md` |26| CLI tool | `[project.scripts]` | `references/library-patterns.md` |27| Framework plugin | `[project.entry-points]` | `references/library-patterns.md` |28| Mixed | primary type + secondary | `references/library-patterns.md` |2930### 2 — Folder layout3132| Situation | Layout |33|---|---|34| New project, unknown size | `src/` layout (safest default) |35| Single-purpose, 1–4 modules | Flat |36| Large, many contributors | `src/` |37| Multiple packages in one repo | Namespace/monorepo |3839Templates: `references/structure-templates.md`.4041### 3 — Build backend4243| Condition | Backend | Config template |44|---|---|---|45| C/Cython extensions OR git-tag versioning | setuptools + setuptools_scm | `references/pyproject-toml.md` |46| All-in-one deps + build + publish | poetry (v2+) | `references/pyproject-toml.md` |47| Minimal config, pure Python | flit | `references/pyproject-toml.md` |48| Modern, fast, pure Python | hatchling | `references/pyproject-toml.md` |4950Backend comparison, naming rules, PyPA concepts: `references/pyproject-toml.md`.5152### 4 — Config + publish5354Scaffold script: `python skills/python-pypi-package-builder/scripts/scaffold.py --name your-package-name`.5556- `references/pyproject-toml.md` — all four backend templates, `py.typed`, tool configs57- `references/ci-publishing.md` — Trusted Publishing, TestPyPI, CHANGELOG, release checklist58- `references/versioning-strategy.md` — PEP 440, semver, setuptools_scm59- `references/testing-quality.md` — ruff/mypy/pre-commit60- `references/release-governance.md` — branch protection, OIDC, tag validation61- `references/tooling-ruff.md` — Ruff-only lint/format62- `references/community-docs.md` — README, CONTRIBUTING, docstrings6364**Two inline rules:**65- `setuptools_scm` CI: `fetch-depth: 0` in every checkout (else version silently falls back to `0.0.0+dev`).66- Library deps: prefer `"httpx>=0.24"` (minimum). Never pin `==` or `~=` in a library's `[project] dependencies.6768## Stop conditions6970- **Don't infer the package type.** Ask the user if unclear.71- **Don't skip TestPyDI for first release.**72- **Don't publish without CI (Trusted Publishing recommended).**7374## Completion criteria7576- [ ] Package type identified (ask if unclear) and folder layout chosen (`src/` vs flat)77- [ ] Build backend selected with `pyproject.toml` from `references/pyproject-toml.md`78- [ ] Scaffold passes `python -m build` and `ruff check` / `mypy`79- [ ] TestPyPI dry-run succeeds before PyPI publish; Trusted Publishing configured8081## Related skills8283- `python-stack-env` — manager detection and env setup before packaging.84- `python-api` — verify signatures after scaffold.
vathymut