pypi-doppler — Claude Code skill: PyPI publishing with Doppler
pypi-doppler — a skill for Claude Code and five other platforms that publishes Python packages to PyPI using a token stored in Doppler — local machine only. The bundled script detects CI environments and exits immediately if one is found.
MIT 123 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill pypi-doppler -a claude-codeWhat pypi-doppler does
The skill adds scripts/publish-to-pypi.sh to the project, which pulls PYPI_TOKEN from the Doppler project private-config and runs uv build followed by uv publish. GitHub Actions handles versioning only — tagging, updating pyproject.toml, and generating the CHANGELOG — but never touches PyPI.
Before each publish, the skill compares the version in pyproject.toml against the latest release on PyPI. If they match, it stops and tells you to create a feat: or fix: commit and let semantic-release run first. That check prevents overwriting an already-published version.
You need Doppler CLI installed (brew install dopplerhq/cli/doppler), authenticated via doppler login, and the PyPI token stored with doppler secrets set PYPI_TOKEN='...' --project private-config --config prd. The script blocks execution inside GitHub Actions, GitLab CI, Jenkins, or CircleCI through CI detection — a deliberate policy recorded in ADR-0027.
What it helps with
- Publish a Python package to PyPI with a Doppler-managed token and no plaintext secrets
- Block accidental publishing from any CI/CD pipeline
- Verify the package version has incremented before release
- Copy and configure
publish-to-pypi.shin a project - Separate automated versioning from manual production publishing
Example prompts for the agent
- Publish the package to PyPI using Doppler credentials locally
- Copy
publish-to-pypi.shfrom the skill intoscripts/and make it executable - Check that the version in
pyproject.tomlis ahead of the current PyPI release, then run./scripts/publish-to-pypi.sh
How to install pypi-doppler
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pypi-doppler -a claude-code2Manually: put the files in place
~/.claude/skills/pypi-doppler/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pypi-doppler/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pypi-doppler -a codex2Manually: put the files in place
.agents/skills/pypi-doppler/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pypi-doppler -a cursor2Manually: put the files in place
.cursor/skills/pypi-doppler/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/itp/skills/pypi-doppler2Manually: put the files in place
.github/skills/pypi-doppler/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pypi-doppler -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/itp/skills/pypi-dopplerManually: put the files in place
.devin/skills/pypi-doppler/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill pypi-doppler -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pypi-doppler
How do I install pypi-doppler in Claude Code?
Run npx skills add terrylica/cc-skills --skill pypi-doppler -a claude-code. The skill is then available at ~/.claude/skills/pypi-doppler/SKILL.md.
What does pypi-doppler do?
It publishes a Python package to PyPI via uv publish, retrieving the token from Doppler. Running it inside a CI pipeline is blocked by the bundled script's CI detection logic.
What do I need before the script can run?
Doppler CLI must be installed and authenticated, and PYPI_TOKEN must be stored in the private-config Doppler project under the prd config. The script also verifies repository ownership to guard against fork abuse.
Source text
SKILL.md · MIT
---
name: pypi-doppler
description: LOCAL-ONLY PyPI publishing with Doppler credentials. TRIGGERS - publish to PyPI, pypi upload, local publish. NEVER use in CI/CD.
allowed-tools: Bash, Read
---
# PyPI Publishing with Doppler (Local-Only)
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## When to Use This Skill
Use this skill when:
- Publishing Python packages to PyPI from local machine
- Setting up Doppler for PyPI token management
- Creating local publish scripts with CI detection guards
- Validating repository ownership before release
## WORKSPACE-WIDE POLICY: LOCAL-ONLY PUBLISHING
**This skill supports LOCAL machine publishing ONLY.**
### FORBIDDEN
- Publishing from GitHub Actions
- Publishing from any CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins, CircleCI)
- `publishCmd` in semantic-release configuration
- Building packages in CI (`uv build` in prepareCmd)
- Storing PyPI tokens in GitHub secrets
### REQUIRED
- Use `scripts/publish-to-pypi.sh` on local machine
- CI detection guards in publish script
- Manual approval before each release
- Doppler credential management (no plaintext tokens)
- Repository verification (prevents fork abuse)
### Rationale
- **Security**: No long-lived PyPI tokens in GitHub secrets
- **Speed**: 30 seconds locally vs 3-5 minutes in CI
- **Control**: Manual approval step before production release
- **Flexibility**: Centralized credential management via Doppler
**See**: ADR-0027, `docs/development/PUBLISHING.md`
---
## Overview
This skill provides **local-only PyPI publishing** using Doppler for secure credential management. It integrates with the workspace-wide release workflow where:
1. **GitHub Actions**: Automated versioning ONLY (tags, releases, CHANGELOG)
2. **Local Machine**: Manual PyPI publishing with Doppler credentials
## Bundled Scripts
| Script | Purpose |
| ------------------------------------------------------------ | ---------------------------------------------- |
| [`scripts/publish-to-pypi.sh`](./scripts/publish-to-pypi.sh) | Local PyPI publishing with CI detection guards |
**Usage**: Copy to your project's `scripts/` directory:
```bash
/usr/bin/env bash << 'DOPPLER_EOF'
# Resolve plugin root using cc-plugin-root helper
PLUGIN_DIR="$(cc-plugin-root itp)"
cp "$PLUGIN_DIR/skills/pypi-doppler/scripts/publish-to-pypi.sh" scripts/
chmod +x scripts/publish-to-pypi.sh
DOPPLER_EOF
```
---
## Prerequisites
### One-Time Setup
1. **Install Doppler CLI**:
```bash
brew install dopplerhq/cli/doppler
```
2. **Authenticate with Doppler**:
```bash
doppler login
```
3. **Verify access to `private-config` project**:
```bash
doppler whoami
doppler projects
```
### PyPI Token Setup
1. **Create PyPI API token**:
- Visit: <https://pypi.org/manage/account/token/>
- Enable 2FA if not already enabled (required since 2024)
- Create token with scope: "Entire account" or specific project
- Copy token (starts with `pypi-AgEIcHlwaS5vcmc...`, ~180 characters)
2. **Store token in Doppler**:
```bash
doppler secrets set PYPI_TOKEN='pypi-AgEIcHlwaS5vcmc...' \
--project private-config \
--config prd
```
3. **Verify token stored**:
```bash
doppler secrets get PYPI_TOKEN \
--project private-config \
--config prd \
--plain
```
---
## Publishing Workflow
### MANDATORY: Verify Version Increment Before Publishing
**Pre-publish validation**: Before publishing to PyPI, verify that the version has incremented from the previous release. Publishing without a version increment is invalid and wastes resources.
**Autonomous check sequence**:
1. Compare local `pyproject.toml` version against latest PyPI version
2. If versions match -- **STOP** - do not proceed with publishing
3. Inform user: "Version not incremented. Run semantic-release first or verify commits include `feat:` or `fix:` types."
### Complete Release Workflow
**Step 1: Development & Commit** (Conventional Commits):
```bash
git add .
git commit -m "feat: add new feature" # MINOR bump
git push origin main
```
**Step 2: Automated Versioning** (GitHub Actions - 40-60s):
GitHub Actions automatically: analyzes commits, determines next version, updates `pyproject.toml`/`package.json`, generates CHANGELOG, creates git tag, creates GitHub release.
**PyPI publishing does NOT happen here** (by design - see ADR-0027).
**Step 3: Local PyPI Publishing** (30 seconds):
```bash
git pull origin main
./scripts/publish-to-pypi.sh
```
### Using Bundled Script (Recommended)
```bash
/usr/bin/env bash << 'GIT_EOF'
# First time: copy script from skill to your project (resolve plugin root via cc-plugin-root)
PLUGIN_DIR="$(cc-plugin-root itp)"
cp "$PLUGIN_DIR/skills/pypi-doppler/scripts/publish-to-pypi.sh" scripts/
chmod +x scripts/publish-to-pypi.sh
# After semantic-release creates GitHub release
git pull origin main
# Publish using local copy of bundled script
./scripts/publish-to-pypi.sh
GIT_EOF
```
**Bundled script features**: CI detection guards, repository verification, Doppler integration, build + publish + verify workflow, clear error messages.
### Manual Publishing (Advanced)
For manual publishing without the canonical script:
```bash
/usr/bin/env bash << 'CONFIG_EOF'
# Retrieve token from Doppler
PYPI_TOKEN=$(doppler secrets get PYPI_TOKEN \
--project private-config \
--config prd \
--plain)
# Build package
uv build
# Publish to PyPI
UV_PUBLISH_TOKEN="${PYPI_TOKEN}" uv publish
CONFIG_EOF
```
**WARNING**: Manual publishing bypasses CI detection guards and repository verification. Use canonical script unless you have a specific reason not to.
---
## Reference Documentation
| Topic | Reference |
| --------------------- | ------------------------------------------------------------------- |
| CI Detection | [CI Detection Enforcement](./references/ci-detection.md) |
| Credential Management | [Doppler & Token Management](./references/credential-management.md) |
| Troubleshooting | [Troubleshooting Guide](./references/troubleshooting.md) |
| TestPyPI Testing | [TestPyPI Testing](./references/testpypi-testing.md) |
| Task Dependency | [Task Dependency](./references/task-dependency.md) |
---
## Related Documentation
- **ADR-0027**: `docs/architecture/decisions/0027-local-only-pypi-publishing.md` - Architectural decision for local-only publishing
- **ADR-0028**: `docs/architecture/decisions/0028-skills-documentation-alignment.md` - Skills alignment with ADR-0027
- **PUBLISHING.md**: `docs/development/PUBLISHING.md` - Complete release workflow guide
- **Bundled Script**: [`scripts/publish-to-pypi.sh`](./scripts/publish-to-pypi.sh) - Reference implementation with CI guards
---
## Validation History
- **2025-12-03**: Refactored to discovery-first, environment-agnostic approach
- `discover_uv()` checks PATH, direct installs, version managers (priority order)
- Supports: curl install, Homebrew, cargo, mise, asdf - doesn't force any method
- **2025-11-22**: Created with ADR-0027 alignment (workspace-wide local-only policy)
- **Validation**: CI detection guards tested, Doppler integration verified
---
**Last Updated**: 2025-12-03 **Policy**: Workspace-wide local-only PyPI publishing (ADR-0027) **Supersedes**: None (created with ADR-0027 compliance from start)
## Post-Execution Reflection
After this skill completes, check before closing:
1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills