OpenSkillIndex← back to search
claude-code

Cc-skills pypi-doppler

LOCAL-ONLY PyPI publishing with Doppler credentials. TRIGGERS - publish to PyPI, pypi upload, local publish. NEVER use in CI/CD.

install
source · Clone the upstream repo
git clone https://github.com/terrylica/cc-skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/terrylica/cc-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/itp/skills/pypi-doppler" ~/.claude/skills/terrylica-cc-skills-pypi-doppler && rm -rf "$T"
manifest: plugins/itp/skills/pypi-doppler/SKILL.md
source content

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

ScriptPurpose
scripts/publish-to-pypi.sh
Local PyPI publishing with CI detection guards

Usage: Copy to your project's 

scripts/
directory:

/usr/bin/env bash << 'DOPPLER_EOF'
# Environment-agnostic path
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/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:

    brew install dopplerhq/cli/doppler

  2. Authenticate with Doppler:

    doppler login

  3. Verify access to 

    claude-config
    project:

    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:

    doppler secrets set PYPI_TOKEN='pypi-AgEIcHlwaS5vcmc...' \
  --project claude-config \
  --config prd

  3. Verify token stored:

    doppler secrets get PYPI_TOKEN \
  --project claude-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):

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):

git pull origin main
./scripts/publish-to-pypi.sh

Using Bundled Script (Recommended)

/usr/bin/env bash << 'GIT_EOF'
# First time: copy script from skill to your project (environment-agnostic)
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/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:

/usr/bin/env bash << 'CONFIG_EOF'
# Retrieve token from Doppler
PYPI_TOKEN=$(doppler secrets get PYPI_TOKEN \
  --project claude-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

TopicReference
CI DetectionCI Detection Enforcement
Credential ManagementDoppler & Token Management
TroubleshootingTroubleshooting Guide
TestPyPI TestingTestPyPI Testing
mise Task Integrationmise Task Integration

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
  • semantic-release Skill: 
    semantic-release
     - Versioning automation (NO publishing)
  • mise-tasks Skill: 
    mise-tasks
     - Task orchestration with dependency management
  • Release Workflow Patterns: 
    release-workflow-patterns.md
     - DAG patterns and anti-patterns
  • Bundled Script: 
    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.