# Publish Python Package Pypi

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-btfranklin-skills-publish-python-package-pypi`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [btfranklin](https://agentstack.voostack.com/s/btfranklin)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [btfranklin](https://github.com/btfranklin)
- **Source:** https://github.com/btfranklin/skills/tree/main/skills/publish-python-package-pypi

## Install

```sh
agentstack add skill-btfranklin-skills-publish-python-package-pypi
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Publish Python Package Pypi

## Overview

Implement a consistent release pipeline for Python packages: CI on push/PR, draft release notes on version tags, and PyPI publish on release publication. Follow the workflow patterns captured in `references/workflow-templates.md`.

## Baseline Pattern

For package repos, maintain these workflow files:
- `.github/workflows/python-package.yml`
- `.github/workflows/draft-release-notes.yml`
- `.github/workflows/python-publish.yml`

Use `references/workflow-templates.md` for canonical templates and version-pinned actions.

## Workflow

1. Identify repository type.
- If repo is an app/service (not a PyPI package), do not add `python-publish.yml` by default.
- If repo is a package/library, continue.

2. Inspect package metadata before workflow changes.
- Confirm `pyproject.toml` has package metadata suitable for publishing.
- Confirm build works locally: `pdm build`.

3. Configure PyPI Trusted Publisher requirements.
- In PyPI project settings, add a Trusted Publisher for this GitHub repository/workflow.
- Use environment `release` in workflow and repository environment settings.
- Do not introduce long-lived PyPI API tokens unless explicitly requested.

4. Add or update `.github/workflows/python-publish.yml`.
- Trigger: `on: release: types: [published]`.
- Permissions: `contents: read` and job-level `id-token: write`.
- Steps: checkout (full history), setup python, install pdm, `pdm build`, `pypa/gh-action-pypi-publish`.
- Keep publish job minimal and deterministic.

5. Ensure CI and release-note workflows exist.
- `python-package.yml` should test/lint on push and PR.
- `draft-release-notes.yml` should trigger on `v*.*.*` tag pushes.
- Keep action versions aligned with repo standards.

6. Validate end-to-end.
- Validate workflow files: `gh workflow list`.
- Validate package build: `pdm build`.
- Validate release path:
  - Push tag `vX.Y.Z` to trigger release notes draft.
  - Publish GitHub release to trigger PyPI publish workflow.
- Check Actions run logs and PyPI project page.

## Required GitHub/PyPI Configuration

1. GitHub Actions secrets:
- Add repository (or org-level) secret `OPENAI_API_KEY` when using `draft-release-notes.yml`.
- `GITHUB_TOKEN` is provided automatically by Actions and does not need manual creation.

2. GitHub environment:
- Create/configure environment `release` if using environment protections.
- Ensure the publish job can run in `release` (reviewers/rules must allow it).

3. PyPI Trusted Publisher:
- In PyPI project settings, register the GitHub repository/workflow/environment used by `python-publish.yml`.
- Do not add `PYPI_API_TOKEN` for trusted publishing unless explicitly requested.

## Repo Conventions

- Use `actions/checkout@v6.0.1`, `actions/setup-python@v6.1.0`, and `pypa/gh-action-pypi-publish@v1.13.0` unless a user asks to change versions.
- Install tooling with:
  - `python -m pip install --upgrade pip`
  - `python -m pip install pdm`
- Match the publish workflow Python version to project support policy. This can vary (`3.10`, `3.11`, `3.12`, `3.14`), so do not hardcode one global value.

## Troubleshooting

1. `Trusted publishing exchange failure`:
- Confirm `id-token: write` exists at job level.
- Confirm PyPI trusted publisher repository/workflow/environment names match exactly.
- Confirm workflow ran from the expected repository and branch/release context.

2. Workflow did not run:
- Confirm event type (`release.published`) and that release is published, not draft only.
- Confirm workflow file exists on default branch.

3. Build artifact problems:
- Run `pdm build` locally and inspect `dist/`.
- Confirm package metadata and included files are correct.

### references/
- `references/workflow-templates.md`: canonical workflow templates and adaptation notes for package repositories.

## Output Expectations

When applying this skill, produce:
1. A short summary of current workflow coverage and gaps.
2. Exact workflow file patches.
3. Any required PyPI/GitHub settings that must be configured manually.
4. Validation results (`pdm build`, workflow/event sanity, and what was not verifiable locally).
5. A checklist of required GitHub/PyPI settings (`OPENAI_API_KEY`, `release` environment, trusted publisher mapping).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [btfranklin](https://github.com/btfranklin)
- **Source:** [btfranklin/skills](https://github.com/btfranklin/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-btfranklin-skills-publish-python-package-pypi
- Seller: https://agentstack.voostack.com/s/btfranklin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.