doppler-workflows — Claude Code skill: secrets and setup
The doppler-workflows skill guides commands that use Doppler secrets for Python package publishing and AWS tasks. It also covers common authentication errors.
MIT 130 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill doppler-workflows -a claude-codeWhat doppler-workflows does
The skill explains how to run commands with Doppler CLI, selecting a project and config and passing the command through --command. Its examples cover publishing to PyPI with uv publish and listing S3 objects with AWS CLI. Without --command, the shell may expand $VAR before Doppler injects the secret.
The guide covers directory-scoped Doppler setup, AWS key rotation, multiple tokens, and errors such as PyPI 403 responses and AWS InvalidClientTokenId. Commands that need secrets require Doppler CLI and the relevant project and config. It warns against injecting GitHub tokens this way and against configuring PyPI publishing in GitHub Actions or CI/CD.
Install it in Claude Code with npx skills add terrylica/cc-skills --skill doppler-workflows -a claude-code. The skill file is placed at ~/.claude/skills/doppler-workflows/SKILL.md.
What it helps with
- pass a PyPI token to a package publishing command through Doppler
- run AWS CLI with secrets from a selected config
- troubleshoot a PyPI
403during publishing - update Doppler after rotating an AWS access key
- find why a command receives an empty
$VAR
Example prompts for the agent
- Publish my Python package to PyPI using
PYPI_TOKENfrom Doppler. - Run
aws s3 lswith secrets from projectaws-credentialsand configdev. - Help me troubleshoot a
403from PyPI during publishing.
How to install doppler-workflows
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill doppler-workflows -a claude-code2Manually: put the files in place
~/.claude/skills/doppler-workflows/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/doppler-workflows/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill doppler-workflows -a codex2Manually: put the files in place
.agents/skills/doppler-workflows/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill doppler-workflows -a cursor2Manually: put the files in place
.cursor/skills/doppler-workflows/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/devops-tools/skills/doppler-workflows2Manually: put the files in place
.github/skills/doppler-workflows/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill doppler-workflows -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/devops-tools/skills/doppler-workflowsManually: put the files in place
.devin/skills/doppler-workflows/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill doppler-workflows -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 doppler-workflows
How do I install doppler-workflows in Claude Code?
Run npx skills add terrylica/cc-skills --skill doppler-workflows -a claude-code. The skill file will be at ~/.claude/skills/doppler-workflows/SKILL.md.
What does doppler-workflows do?
It guides commands that use Doppler secrets, including PyPI publishing and AWS operations. It also covers credential rotation and authentication troubleshooting.
Why does Doppler use the --command option?
It lets Doppler inject variables before the command runs. Without it, the shell can expand $VAR first and pass an empty value.
Source text
SKILL.md · MIT
---
name: doppler-workflows
description: Manage credentials and secrets through Doppler for publishing and deployment workflows. Use whenever the user needs to publish Python packages.
allowed-tools: Read, Bash
---
# Doppler Credential Workflows
> **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
- Rotating AWS access keys
- Managing credentials across multiple services
- Troubleshooting authentication failures (403, InvalidClientTokenId)
- Setting up Doppler credential injection patterns
- Multi-token/multi-account strategies
## Quick Reference
## Core Pattern: Doppler CLI
**Standard Usage:**
```bash
doppler run --project <project> --config <config> --command='<command>'
```
**Why --command flag:**
- Official Doppler pattern (auto-detects shell)
- Ensures variables expand AFTER Doppler injects them
- Without it: shell expands `$VAR` before Doppler runs → empty string
---
## Quick Start Examples
### PyPI Publishing
```bash
doppler run --project private-config --config dev \
--command='uv publish --token "$PYPI_TOKEN"'
```
### AWS Operations
```bash
doppler run --project aws-credentials --config dev \
--command='aws s3 ls --region $AWS_DEFAULT_REGION'
```
---
## Best Practices
1. Always use --command flag for credential injection
2. Use project-scoped tokens (PyPI) for better security
3. Rotate credentials regularly (90 days recommended)
4. Document with Doppler notes: `doppler secrets notes set <SECRET> "<note>"`
5. Use stdin for storing secrets: `echo -n 'secret' | doppler secrets set`
6. Test injection before using: `echo ${#VAR}` to verify length
7. Multi-token naming: `SERVICE_TOKEN_{ABBREV}` for clarity
---
## Reference Documentation
For detailed information, see:
- [PyPI Publishing](./references/pypi-publishing.md) - Token setup, publishing, troubleshooting
- [AWS Credentials](./references/aws-credentials.md) - Rotation workflow, setup, troubleshooting
- [Multi-Service Patterns](./references/multi-service-patterns.md) - Multiple PyPI packages, multiple AWS accounts
- [AWS Workflow](./AWS_WORKFLOW.md) - Complete AWS credential management guide
**Bundled Specifications:**
- `PYPI_REFERENCE.yaml` - Complete PyPI spec
- `AWS_SPECIFICATION.yaml` - AWS credential architecture
---
## Local Development: Directory-Scoped Doppler Config
For local development, bind the project directory to its Doppler project/config once, then scope each command with `doppler run`:
```bash
cd ~/project && doppler setup --project private-config --config prd --no-interactive
doppler run -- COMMAND # secrets such as PYPI_TOKEN exist for this command only
```
For a value needed across several commands in one shell, export it explicitly: `export PYPI_TOKEN="$(doppler secrets get PYPI_TOKEN --plain)"`.
> **Do NOT inject GitHub tokens this way (ADR 2026-06-21).** GitHub multi-account auth is driven by the repo's `origin` host-alias (`[email protected]<account>:…`). A token resolves fresh per-repo via `~/.claude/tools/bin/gh-token-for-repo`; an ambient `GH_TOKEN` outranks the isolated gh profile and 401s after a rotation. The `.secrets/gh-token-*` files are deleted.
---
## PyPI Publishing Policy
<!-- ADR: 2025-12-10-clickhouse-skill-documentation-gaps -->
For PyPI publishing, see [`pypi-doppler` skill](../../../itp/skills/pypi-doppler/SKILL.md) for **LOCAL-ONLY** workspace policy.
**Do NOT** configure PyPI publishing in GitHub Actions or CI/CD pipelines.
---
## Troubleshooting
| Issue | Cause | Solution |
| -------------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| 403 on PyPI publish | Token expired or wrong scope | Regenerate project-scoped token, update in Doppler |
| InvalidClientTokenId (AWS) | Access key rotated or deleted | Run AWS key rotation workflow, update Doppler |
| Variable expands empty | Using `$VAR` without --command | Always use `--command='...$VAR...'` pattern |
| Doppler CLI not found | Not installed | `brew install dopplerhq/cli/doppler` |
| Wrong config selected | Ambiguous project/config | Specify both `--project` and `--config` explicitly |
| Wrong project picked up | Directory not bound or bound wrongly | `doppler configure` to inspect; re-run `doppler setup` |
| Secret retrieval slow | One `doppler secrets get` per call | Fetch once per shell with `export VAR="$(doppler secrets get VAR --plain)"` |
| Token length mismatch | Copied with extra whitespace | Trim token: `echo -n 'secret' \| doppler secrets set` |
## 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