Vercel Deploy

Use this skill when the job is operating a deployment on Vercel specifically, not designing generic rollout policy.

vercel-deploy is the provider-specific front door for:

• creating or refreshing Vercel preview deployments
• running a direct production deployment on Vercel
• staging a deploy, verifying it, then promoting it live
• assigning a stable preview alias or attaching a custom domain
• inspecting/fixing Vercel environment-variable scope and redeploy needs
• responding to a bad production deployment with rollback-oriented checks

Read these support docs before choosing the mode:

• references/modes-and-boundaries.md
• references/preview-production-command-packets.md
• references/env-domain-rollback-troubleshooting.md

When to use this skill

• The user explicitly wants to deploy a project on Vercel
• The job is about a Vercel preview URL, preview alias, or stable demo environment
• A linked Vercel deployment already exists and needs promotion or rollback handling
• The main issue is Vercel env scope, Vercel domain/alias state, or Vercel-specific release verification
• The provider has already been chosen and the user needs Vercel operator guidance rather than vendor-neutral release design

When not to use this skill

• The main question is generic rollout strategy, release gating, canary policy, or cross-provider deployment design → use deployment-automation
• The main job is editing GitHub Actions / CI YAML / task runners around the deploy flow → use deployment-automation
• The main job is installing Node, Vercel CLI, auth bootstrap, or linking the local machine → use system-environment-setup
• The app/framework/build is broken before the deploy path itself works → use debugging or the relevant framework/build skill first
• The main job is long-lived telemetry, SLOs, or alerting after release → use monitoring-observability

Instructions

Step 1: Normalize the Vercel job into one packet

Choose exactly one primary mode before reaching for commands.

vercel_packet:
  primary_mode: preview-deploy | production-deploy | promote-preview | alias-domain | env-sync | rollback-response
  project_state: linked | unlinked | unknown
  build_mode: source-build | prebuilt | unknown
  target_environment: preview | production | development | custom | unknown
  url_goal: generated-url | stable-preview-alias | custom-domain | mixed | none
  verification_depth: none | smoke | health-plus-logs | release-checklist

Primary modes:

• preview-deploy — create or refresh a testable Vercel preview
• production-deploy — run a direct fresh production deployment
• promote-preview — verify an existing deployment, then make it current
• alias-domain — apply/verify a stable preview alias or custom domain
• env-sync — fix environment-variable scope or stale local/project env state
• rollback-response — move production back to a known-good deployment and verify recovery

If the request contains multiple goals, pick the one that owns the first answer and route the rest explicitly.

Step 2: Gather only the minimum truthful evidence

Do not guess from the framework name alone. Confirm the smallest credible set first:

1. Is the project already linked to Vercel (vercel link, .vercel/project.json, or dashboard evidence)?
2. Is the target really preview, production, or a custom/development environment?
3. Is the deploy path source-based or prebuilt?
4. Does the user care about the generated deployment URL, a stable alias, or a custom domain?
5. Is this actually a deploy/cutover problem, or an env/config mismatch that still needs redeploy?
6. What proof is expected: URL only, smoke check, health + logs, DNS verification, or rollback verification?

If one item is unknown, state the assumption instead of pretending the mode is fully known.

Step 3: Use the matching operator path

Do not dump every command at once. Pick the reference packet that matches the mode.

A. preview-deploy

Use when the deliverable is a testable preview deployment.

• Prefer linked-project CLI or dashboard-backed preview flows.
• Return the generated deployment URL plus any stable alias plan.
• If the goal is a stable demo URL, carry the result into alias-domain rather than mixing everything into one blob.

Use packet: references/preview-production-command-packets.md#preview-deploy-packet

B. production-deploy

Use when the user explicitly wants a fresh production deployment now.

• Say whether the deployment is source-build or prebuilt.
• Report the production URL/domain reached.
• Separate deploy success from post-deploy verification.

Use packet: references/preview-production-command-packets.md#direct-production-deploy-packet

C. promote-preview

Use when a deployment already exists and the job is to cut over safely.

• Verify the exact deployment URL/commit before promotion.
• Treat promotion as a release operation, not a magical pointer flip.
• Note team-scope or domain caveats when they matter.
• Report production verification separately from the promote command itself.

Use packet: references/preview-production-command-packets.md#staged-production--promote-packet

D. alias-domain

Use when the stable URL is the real deliverable.

• Distinguish generated URL vs stable preview alias vs production custom domain.
• Report DNS/manual verification status separately from CLI success.
• Keep the raw deployment URL available as fallback evidence.

Use packet: references/env-domain-rollback-troubleshooting.md#aliases-and-domains

E. env-sync

Use when preview/prod behavior differs because variables are missing, stale, or scoped incorrectly.

• Check the intended environment first.
• Call out that env-var changes apply to new deployments, not old ones.
• Distinguish Vercel env scope from app-level canonical URL/config expectations.

Use packet: references/env-domain-rollback-troubleshooting.md#environment-variables

F. rollback-response

Use when production traffic must revert quickly.

• Identify the currently bad deployment and the exact rollback target.
• Call out stale-config / cron / plan-limit caveats before claiming recovery.
• Re-check production logs/health after rollback.

Use packet: references/env-domain-rollback-troubleshooting.md#rollback

Step 4: Keep boundaries clean while answering

Use this route-out table whenever the request drifts.

Step 5: Mention the legacy claimable deploy helper only if the environment explicitly depends on it

This directory still ships scripts/deploy.sh, a claimable-preview helper that packages a tarball and returns preview/claim URLs. Treat it as a legacy environment-specific shortcut, not the default Vercel operating model.

Use it only when all of these are true:

• the runtime explicitly expects the claimable deploy endpoint
• the job is just creating a claimable preview URL
• linked-project, promotion, alias/domain, env-sync, and rollback operations are out of scope

Otherwise prefer the official Vercel CLI / dashboard model described above.

Output format

Return a mode-specific packet instead of a loose command dump.

Minimum structure:

# Vercel Operation Summary
- Mode:
- Project linked:
- Build mode:
- Target environment:
- URL / deployment:
- Verification performed:
- Remaining risk or manual step:
- Routed-out work (if any):

Examples

Example 1: Preview deploy with stable alias

User asks: “Deploy this Next.js branch to Vercel and give me a stable preview URL.”

Expected move:

• choose preview-deploy as the primary mode
• deploy via the preview packet
• capture the generated deployment URL
• apply or plan a stable alias separately
• return both URLs and any DNS/manual step still needed

Example 2: Promote a verified staged deployment

User asks: “This Vercel build already passed QA. Promote it to production and verify it.”

Expected move:

• choose promote-preview as the primary mode
• verify the exact deployment/commit first
• run the staged-production promote packet
• report production verification after promotion
• mention scope/domain caveats if they apply

Example 3: Vercel env vars not showing up in deploys

User asks: “The variable is in Vercel, but the deployment can’t read it.”

Expected move:

• choose env-sync
• verify the intended environment scope
• confirm whether a new deployment happened after the env change
• use Vercel env inspection/pull as the trusted state check
• call out any app-level canonical URL/config still required

Example 4: Route out generic release design

User asks: “Help me design our staging-to-prod rollout policy and canary rules across providers.”

Expected move:

• do not pretend this is a Vercel-only operation
• route the main job to deployment-automation
• keep only any explicitly Vercel-specific follow-up inside vercel-deploy

Best practices

1. Pick one primary Vercel mode before giving commands.
2. Prefer linked-project, official CLI/dashboard flows over legacy tarball shortcuts.
3. Treat deploy, promote, alias/domain, env repair, and rollback as distinct operator packets.
4. Always distinguish generated deployment URLs, stable preview aliases, and custom domains.
5. Remember that env-var changes only affect new deployments.
6. Do not oversell vercel promote or rollback as lossless; call out scope/domain/plan/config caveats.
7. Route generic rollout design back to deployment-automation to avoid overlap.

References

• Deploying Projects from Vercel CLI
• vercel deploy
• vercel promote
• vercel rollback
• Environment variables
• System environment variables
• Working with domains
• Deploying Git Repositories with Vercel