Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill pypi-doppler -a claude-code
Open on GitHub

What 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.sh in 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.sh from the skill into scripts/ and make it executable
  • Check that the version in pyproject.toml is 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-code

2Manually: put the files in place

~/.claude/skills/pypi-doppler/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pypi-doppler/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set79

The whole set →
implement-plan-preflight implement-plan-preflight runs the ITP workflow preflight phase to generate MADR 4.0 architecture records, design specs, and linked diagrams. CX Codex +1 125installs issues-workflow issues-workflow puts plan, hierarchy and status into GitHub Issues: sub-issues under a parent, an issue linked to its branch and pull request, and a close on merge. CX Codex +1 124installs ml-failfast-validation ml-failfast-validation is a Claude Code skill that runs preflight checks for machine learning experiments, catching tensor, schema, and gradient errors before long training jobs. CX Codex +1 124installs pr-gfm-validator pr-gfm-validator turns relative markdown links in a pull request body into absolute blob URLs pinned to your feature branch, so reviewers stop landing on 404s. CX Codex +1 123installs schema-e2e-validation The schema-e2e-validation skill runs YAML schema generation and Earthly E2E checks. Use it before committing schema changes or to compare a contract with ClickHouse Cloud. CX Codex +1 123installs plugin-validator plugin-validator — a skill that validates plugin structure before release and catches silent failures in hooks—error-handling gaps in shell commands and unhandled Python exceptions. Essential before publishing to the marketplace. CX Codex +1 122installs evolutionary-metric-ranking evolutionary-metric-ranking is a Claude Code skill that ranks and filters model and strategy configurations across multiple metrics using percentile cutoffs, intersection rules, and evolutionary search. CX Codex +1 121installs pre-ship-review The pre-ship-review skill runs structured quality checks before a pull request, release, or milestone. It catches integration failures where contracts, examples, and tests must align across files. CX Codex +1 120installs

Project sponsors

Companies that keep this analytics open