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:

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

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-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.

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

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 promote or rollback as lossless; call out scope/domain/plan/config caveats.
Route generic rollout design back to deployment-automation to avoid overlap.

vercel-deploy

Vercel Deploy

When to use this skill

When not to use this skill

Instructions

Step 1: Normalize the Vercel job into one packet

Step 2: Gather only the minimum truthful evidence

Step 3: Use the matching operator path

A. preview-deploy

B. production-deploy

C. promote-preview

D. alias-domain

E. env-sync

F. rollback-response

Step 4: Keep boundaries clean while answering

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

Output format

Examples

Example 1: Preview deploy with stable alias

Example 2: Promote a verified staged deployment

Example 3: Vercel env vars not showing up in deploys

Example 4: Route out generic release design

Best practices

References

A. `preview-deploy`

B. `production-deploy`

C. `promote-preview`

D. `alias-domain`

E. `env-sync`

F. `rollback-response`