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
workflow-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
debuggingor 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-checklistPrimary modes:
preview-deploy— create or refresh a testable Vercel previewproduction-deploy— run a direct fresh production deploymentpromote-preview— verify an existing deployment, then make it currentalias-domain— apply/verify a stable preview alias or custom domainenv-sync— fix environment-variable scope or stale local/project env staterollback-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:
- Is the project already linked to Vercel (
vercel link,.vercel/project.json, or dashboard evidence)? - Is the target really preview, production, or a custom/development environment?
- Is the deploy path source-based or prebuilt?
- Does the user care about the generated deployment URL, a stable alias, or a custom domain?
- Is this actually a deploy/cutover problem, or an env/config mismatch that still needs redeploy?
- 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-domainrather 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.
| If the request sounds like... | Use |
|---|---|
| “Design the release gates, canary policy, or rollback strategy across providers” | deployment-automation |
| “Rewrite the GitHub Actions workflow that runs Vercel commands” | workflow-automation |
| “Install Vercel CLI, auth, Node, or link local credentials” | system-environment-setup |
| “The build crashes before deploy succeeds” | debugging or a framework-specific skill |
| “Set up dashboards, alerts, or long-lived post-release monitoring” | monitoring-observability |
| “Inspect, deploy, promote, alias, domain-manage, env-sync, or roll back on Vercel” | vercel-deploy |
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-deployas 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-previewas 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
- Pick one primary Vercel mode before giving commands.
- Prefer linked-project, official CLI/dashboard flows over legacy tarball shortcuts.
- Treat deploy, promote, alias/domain, env repair, and rollback as distinct operator packets.
- Always distinguish generated deployment URLs, stable preview aliases, and custom domains.
- Remember that env-var changes only affect new deployments.
- Do not oversell
vercel promoteor rollback as lossless; call out scope/domain/plan/config caveats. - Route generic rollout design back to
deployment-automationto avoid overlap.