python-pypi-package-builder
Helps your agent build and publish high-quality Python packages. It handles testing, versioning, and publishing so others can use your code.
What it does
This guide helps you build, test, and publish Python libraries to PyPI (the Python package 'marketplace'). It covers everything from code organization to the final release, ensuring your package works well and is easy for other developers to use.
When to use it
- ✓When you want to create your first Python library to share.
- ✓When you need to publish a Python package to PyPI.
- ✓To organize and test an existing Python project.
Example of what to ask your AI
“How do I create and publish a Python library named 'my_utility'?”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
The guide helps you choose the best way to organize your code and the right tools to build, test, and publish your package. It also explains how to version your package and use modern features like 'type hints'.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add github/awesome-copilot --skill python-pypi-package-builderOr download just the file:
curl -L https://raw.githubusercontent.com/github/awesome-copilot/main/skills/python-pypi-package-builder/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
Python PyPI Package Builder Skill
A complete, battle-tested guide for building, testing, linting, versioning, typing, and publishing a production-grade Python library to PyPI — from first commit to community-ready release.
AI Agent Instruction: Read this entire file before writing a single line of code or creating any file. Every decision — layout, backend, versioning strategy, patterns, CI — has a decision rule here. Follow the decision trees in order. This skill applies to any Python package type (utility, SDK, CLI, plugin, data library). Do not skip sections.
Quick Navigation
| Section in this file | What it covers |
|---|---|
| 1. Skill Trigger | When to load this skill |
| 2. Package Type Decision | Identify what you are building |
| 3. Folder Structure Decision | src/ vs flat vs monorepo |
| 4. Build Backend Decision | setuptools / hatchling / flit / poetry |
| 5. PyPA Packaging Flow | The canonical publish pipeline |
| 6. Project Structure Templates | Full layouts for every option |
| 7. Versioning Strategy | PEP 440, semver, dynamic vs static |
| Reference file | What it covers |
|---|---|
references/pyproject-toml.md |
All four backend templates, setuptools_scm, py.typed, tool configs |
references/library-patterns.md |
OOP/SOLID, type hints, core class design, factory, protocols, CLI |
references/testing-quality.md |
conftest.py, unit/backend/async tests, ruff/mypy/pre-commit |
references/ci-publishing.md |
ci.yml, publish.yml, Trusted Publishing, TestPyPI, CHANGELOG, release checklist |
references/community-docs.md |
README, docstrings, CONTRIBUTING, SECURITY, anti-patterns, master checklist |
references/architecture-patterns.md |
Backend system (plugin/strategy), config layer, transport layer, CLI, backend injection |
references/versioning-strategy.md |
PEP 440, SemVer, pre-release, setuptools_scm deep-dive, flit static, decision engine |
references/release-governance.md |
Branch strategy, branch protection, OIDC, tag author validation, prevent invalid tags |
references/tooling-ruff.md |
Ruff-only setup (replaces black/isort), mypy config, pre-commit, asyncio_mode=auto |
Scaffold script: run python skills/python-pypi-package-builder/scripts/scaffold.py --name your-package-name
to generate the entire directory layout, stub files, and pyproject.toml in one command.
1. Skill Trigger
Load this skill whenever the user wants to:
- Create, scaffold, or publish a Python package or library to PyPI
- Build a pip-installable SDK, utility, CLI tool, or framework extension
- Set up
pyproject.toml, linting, mypy, pre-commit, or GitHub Actions for a Python project - Understand versioning (
setuptools_scm, PEP 440, semver, static versioning) - Understand PyPA specs:
py.typed,MANIFEST.in,RECORD, classifiers - Publish to PyPI using Trusted Publishing (OIDC) or API tokens
- Refactor an existing package to follow modern Python packaging standards
- Add type hints, protocols, ABCs, or dataclasses to a Python library
- Apply OOP/SOLID design patterns to a Python package
- Choose between build backends (setuptools, hatchling, flit, poetry)
Also trigger for phrases like: "build a Python SDK", "publish my library", "set up PyPI CI", "create a pip package", "how do I publish to PyPI", "pyproject.toml help", "PEP 561 typed", "setuptools_scm version", "semver Python", "PEP 440", "git tag release", "Trusted Publishing".
2. Package Type Decision
Identify what the user is building before writing any code. Each type has distinct patterns.
Decision Table
| Type | Core Pattern | Entry Point | Key Deps | Example Packages |
|---|---|---|---|---|
| Utility library | Module of pure functions + helpers | Import API only | Minimal | arrow, humanize, boltons, more-itertools |
| API client / SDK | Class with methods, auth, retry logic | Import API only | httpx or requests |
boto3, stripe-python, openai |
| CLI tool | Command functions + argument parser | [project.scripts] or [project.entry-points] |
click or typer |
black, ruff, httpie, rich |
…
FAQ
What is PyPI?
PyPI stands for Python Package Index. It's an online repository where Python developers publish and share libraries (packages) that others can install and use in their projects.
What are 'build backends' (setuptools, hatchling, flit, poetry)?
These are different tools Python uses to package your code, turning it into a format that can be installed via pip and published to PyPI. Each has its own advantages.
What are 'type hints'?
'Type hints' are annotations you add to your Python code to indicate the data type a variable or function expects or returns. This helps catch errors early and makes the code easier to understand.
Details
Original description by the author
End-to-end skill for building, testing, linting, versioning, and publishing a production-grade Python library to PyPI. Covers all four build backends (setuptools+setuptools_scm, hatchling, flit, poetry), PEP 440 versioning, semantic versioning, dynamic git-tag versioning, OOP/SOLID design, type hints (PEP 484/526/544/561), Trusted Publishing (OIDC), and the full PyPA packaging flow. Use for: creat
repo: github/awesome-copilot
Popularity
- GitHub stars
- 40k
- Ranking position
- #5295
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
acquire-codebase-knowledge
Helps your agent understand and document an existing code project. It's useful for onboarding new people or getting an overview of the architecture.
github/awesome-copilot
acreadiness-assess
Enables your agent to assess a project's readiness for AI and generate a report. It's useful for understanding how well a project is prepared to use AI tools.
github/awesome-copilot
acreadiness-generate-instructions
Helps your agent create instructions for AI tools based on an assessment. It's useful for improving how AI interacts with code and closing identified gaps.
github/awesome-copilot
acreadiness-policy
Enables your agent to help define or apply policies for AI project assessment. It's useful for standardizing how projects are evaluated and ensuring compliance.
github/awesome-copilot
Similar skills
api-connector-builder
Has your agent build new API connections following the existing pattern. Use when you need to add one more integration without creating a new way of doing things.
affaan-m/ECC
api-design
Helps your agent design REST APIs following best practices. It's useful for defining how APIs communicate, how errors are shown, and how to organize data.
affaan-m/ECC
backend-patterns
Helps your agent with server-side architecture patterns and database optimization. It's useful for building or reviewing code that runs on the server.
affaan-m/ECC