deploy-setup— agent skill

You are walking a developer through the first deploy of a Starter Series project. The project has been scaffolded (via create-starter skill / CLI / MCP) and is on disk; this skill takes it from "scaffolded" to "first release published."

Prerequisites

• The project is already scaffolded and on disk. Verify by checking for .github/workflows/cd*.yml and package.json / pyproject.toml / Dockerfile.
• gh CLI is installed and authenticated (gh auth status). If not, instruct the user.
• A GitHub repository exists for the project. If not, offer gh repo create.

Workflow

Step 1: Detect the template

Read these files to identify which starter the project came from:

Report the detected template name to the user.

Step 2: Inspect the CD workflow

Read .github/workflows/cd.yml (or cd-android.yml + cd-ios.yml for react-native, or cd-firefox.yml for browser-extension). Extract:

• The list of secrets.X referenced in with: / env: / if: blocks. These are the secrets that must be set.
• Whether the workflow uses OIDC trusted publishing (look for id-token: write in permissions: and npm publish --provenance / pypa/gh-action-pypi-publish in steps). If yes, the publish step needs no token secret — only registry-side configuration (web UI). If no, a token secret is required.

Step 3: Required secrets matrix (per template)

If the user wants verbatim guidance, use this table:

Step 4: Diff against existing secrets

Run gh secret list -R <owner>/<repo> to see what's already set. Subtract from the required list. For each missing secret, ask the user:

"I need a value for VSCE_PAT. This is a Personal Access Token with Marketplace > Manage scope from https://dev.azure.com/_usersSettings/tokens. Paste the token (it will be masked):"

Then run gh secret set VSCE_PAT --body "$value" -R <owner>/<repo>.

Never echo the value to the conversation, never write it to disk, never include it in git commit messages.

Step 5: OIDC trusted publishing setup (where applicable)

For mcp-server, npm-package, create-starter, mcp-server-python:

The CD workflow requires registry-side trusted publisher registration before the first publish. Provide the user with:

• npm: link to https://www.npmjs.com/settings/<their-org-or-user>/packages → select package → Trusted Publishers → "Add GitHub Actions" with the repo + workflow filename. Tell them: "Your npm account must have 2FA on writes enabled for trusted publishing to be available."
• PyPI: link to https://pypi.org/manage/account/publishing/ → "Add a new pending publisher" with the GitHub org, repo name, workflow filename, and (optionally) environment name.

These steps cannot be automated via gh — they're registry-side web UI. Provide the URL and exact field values.

Step 6: Trigger the first deploy

Once secrets are in place and OIDC is registered:

# Bump version first (some templates require this; check cd.yml's version-guard step)
npm run version:patch  # or version:minor, or version:major

# Commit + push the version bump
git commit -am "chore: bump version for first release"
git push

# Trigger the CD workflow
gh workflow run cd.yml -R <owner>/<repo>

# Watch the run
gh run watch -R <owner>/<repo>

For tag-triggered repos (docker-deploy uses push: tags: v*), instead:

git tag v0.1.0
git push origin v0.1.0

Step 7: Verify the release

After the run finishes:

gh release view -R <owner>/<repo>

For npm: npm view <package-name> shows the published version. For PyPI: pip index versions <package-name> (or visit pypi.org/p/<name>). For Marketplace: visit https://marketplace.visualstudio.com/items?itemName=<publisher>.<name>. For GHCR: docker pull ghcr.io/<owner>/<repo>:<version>.

Dry-run mode

If the user asks for a dry run, do everything except gh secret set and gh workflow run. Print the would-be commands and the secret names you'd request. Useful for review before committing to a deploy.

Output format

Walk the user through one numbered step at a time. After each interactive prompt, summarize what got set / what's pending. End with a "Next: trigger cd.yml" once secrets and OIDC are in place.

Edge cases

• Repo not yet created: offer gh repo create <name> --public --source=. --push and re-detect after.
• Multiple cd workflows (react-native, browser-extension): detect both, run their secret matrices in sequence.
• GH_TOKEN already a default: GitHub Actions provides secrets.GITHUB_TOKEN automatically with read+write to the same repo. Don't ask the user to set it.
• Existing failed run: if there's a failed run on cd.yml, surface the failure with gh run view <id> --log-failed | head -50 so we don't blindly retrigger.
• User aborts mid-flow: do not auto-retry. Save progress in a one-line .deploy-setup.checkpoint file at repo root listing which secrets/OIDC steps are done, and resume from there next invocation. (Optional — only if user asks.)

Safety rails

• Never put a token value in a chat message you produce. Always pipe to gh secret set --body "$VALUE".
• Never modify CD workflows during this skill — it's setup, not editing. If a workflow looks wrong, surface it but ask the user before touching.
• Never publish without the user explicitly confirming "yes, run cd.yml now."
• For first npm/PyPI publishes, recommend the user manually trigger once with workflow_dispatch (auditable) before any tag-based automation.