deploy-to-vercel

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• deploy my app
• deploy this to Vercel
• deploy and give me the link
• push this live
• create a preview deployment

Renamed upstream: this skill shipped originally as vercel-deploy-claimable (claimable-ownership demo deploys). Vercel Labs has since renamed and broadened it to deploy-to-vercel (v3.0.0), with state-aware routing across git push / CLI deploy / link-first. The wiki entry still lives at /skills/vercel-deploy-claimable/ for URL stability; the content below tracks the current upstream skill.

What it does

deploy-to-vercel is Vercel Labs’ canonical agent skill for shipping a project to Vercel from inside a Claude Code session. The skill is structured as a two-step flow:

Step 1 — gather project state. Four checks before deciding anything:

1. git remote get-url origin — is there a remote?
2. cat .vercel/project.json or .vercel/repo.json — is the project linked to Vercel?
3. vercel whoami — is the CLI authenticated?
4. vercel teams list --format json — which teams are available?

If the user belongs to multiple teams, the skill asks which team to deploy to (one bulleted prompt, no additional confirmation after the pick). If the project is already linked, the orgId in .vercel/project.json / .vercel/repo.json determines the team automatically.

Step 2 — choose a deploy method based on state.

• Linked + has git remote → git push. The ideal state. Skill asks once before pushing, then git add / git commit / git push. Vercel builds from the push; non-production branches get preview deployments, the production branch gets a production deployment. Preview URL retrieved via vercel ls --format json (latest entry’s url).
• Linked + no git remote → vercel deploy [path] -y --no-wait. Direct CLI deploy. --no-wait returns immediately with the deployment URL instead of blocking until build finishes. Status checked with vercel inspect <url>.
• Not linked → vercel link first, then route to one of the above based on git state.

Preview-by-default rule. The skill always deploys as preview unless the user explicitly asks for production. Production deploys use --prod and are gated on explicit user intent.

When to use it

Reach for it when:

• You want a working preview URL in <90 seconds for review, demo, or handoff
• The project is already linked to Vercel and a git push should ship it — the skill handles the “ask before push” gate so you don’t accidentally trigger production
• The project is not linked and you want the link-first flow without manually invoking vercel link
• You belong to multiple Vercel teams and want the team-selection prompt to be predictable rather than ad-hoc

When not to reach for it:

• Production deployments where the change needs review or CI verification before going live — deploy via your normal CI/CD pipeline, not this skill
• Apps that depend on env vars, secrets, or backend infrastructure that aren’t already configured on Vercel — the skill deploys the project as-is; missing secrets surface as runtime errors
• Codebases on a different host (Cloudflare Pages, Netlify, Render) — the skill is Vercel-specific by design

Install

From the Vercel Labs agent-skills repo. The skill orchestrates Vercel’s CLI, so a working vercel CLI install + auth (vercel login) is required. For the linked-with-git-remote path, the project also needs to be linked (vercel link) and have a git remote pointing somewhere Vercel has a deploy integration with (typically GitHub).

What a session looks like

A typical session has three phases:

1. State gather. The agent runs the four detection commands. Output dictates the next branch.
2. Method pick. Based on state: git push (linked + remote), vercel deploy (linked, no remote), or vercel link first (not linked). Multi-team users get one prompt to pick the team.
3. Deploy. Preview URL surfaces within the response. For git-push paths, the URL comes from vercel ls --format json after a brief sleep 5. For direct-CLI paths, the URL comes back immediately via --no-wait.

The discipline that makes it work: the state check is upfront and exhaustive, so the deploy method is never guessed. The preview-by-default rule guards against accidental production pushes — even on a main branch, the skill stays in preview unless the user explicitly elevates.

Receipts

Where it works well:

• Quick demo handoffs: a working preview URL in under 90 seconds for any framework Vercel auto-detects (Next.js, Remix, Astro, SvelteKit, etc.)
• Onboarding fresh projects: the vercel link → deploy chain is one skill activation instead of a manual CLI tutorial
• Multi-team accounts: the team selection prompt is consistent and uses --scope correctly across deploy / link / inspect

Where it backfires:

• Apps with env vars or secrets that aren’t already configured on Vercel deploy as broken — the skill doesn’t carry secrets over and doesn’t error-out gracefully; missing env vars surface as runtime errors
• The preview-by-default rule is a feature, not a bug, but a user expecting “deploy = production” needs to know to add --prod (or say “deploy to production”)
• The earlier “claimable ownership” flow that this skill used to be famous for (anonymous deploy URL → transfer to a Vercel account later) is no longer the primary path in v3.0.0 — that workflow has been deprioritised in favour of the link-first / git-push pattern

Pattern that works: if the goal is preview / demo / handoff (most common case), let the skill route through git push when the project is linked and you have a remote — that’s the cleanest path and matches the long-term setup Vercel’s own docs recommend.

Source and attribution

From the Vercel Labs agent-skills repository. Maintained by Vercel Labs. Current upstream version: v3.0.0.

License: MIT.

For the canonical SKILL.md, the full step-by-step deploy table, and any updates, defer to the source repo.