Vercel CLI with Tokens

tl;dr: this skill is the non-interactive deploy path for the Vercel CLI. It enforces one safety rule the agent otherwise gets wrong — VERCEL_TOKEN is read from the environment, never passed as a --token flag (shell history leaks). Beyond that, it walks a four-step playbook: find the token, find the project + team, link or skip linking, then deploy. Default is preview, not production. Default is asking the user before git push. Default is -y --no-wait so the agent does not block.

What it actually does

SKILL.md (version 1.0.0, 2026-09-10) walks the agent through four scenarios in order to locate the token:

A) printenv VERCEL_TOKEN          → if set, skip ahead
B) grep '^VERCEL_TOKEN=' .env     → export it
C) grep -i 'vercel' .env          → identify the variable name, then export as VERCEL_TOKEN
D) nothing found                  → ask the user for one (vercel.com/account/tokens)

If none yield a token, the skill stops and asks. It does not fall back to vercel login — that is the whole point of this skill.

Once VERCEL_TOKEN is exported, the agent looks for VERCEL_PROJECT_ID and VERCEL_ORG_ID. The skill is explicit: both must be set together, setting only one causes an error.

Deploy choice is a small decision tree:

• Have VERCEL_TOKEN + VERCEL_PROJECT_ID in env → vercel deploy -y --no-wait (no vercel link needed).
• Have VERCEL_TOKEN + team slug only → vercel deploy --scope <team> -y --no-wait.
• Have token + team but no project ID → check .vercel/project.json / .vercel/repo.json, run vercel link --repo --scope <team> -y if a git remote exists, else vercel link --scope <team> -y, then deploy.

The skill also covers the quieter ops: vercel env add / ls / pull / rm, vercel ls --format json, vercel inspect <url> --logs, vercel domains ls / add, and Stripe Projects plan changes (stripe projects add vercel/pro, stripe projects upgrade vercel-plan pro).

When the agent should load it

The description field enumerates the trigger phrases:

• “Deploy to vercel”
• “Set up vercel”
• “Add environment variables to vercel”

If the user wants interactive auth (vercel login) this is the wrong skill — they want the standard human flow, not the agent flow. If they want cost/performance audit, they want vercel-optimize from the same repo.

Install

# installs the whole vercel-labs/agent-skills pack
npx skills add vercel-labs/agent-skills

The npx skills add invocation is what the upstream README documents. If your host does not speak the Agent Skills loader (or you want just this one skill), clone the repo and point the agent at the file:

git clone https://github.com/vercel-labs/agent-skills
# Claude Code / Cursor pick up SKILL.md from:
#   ~/.claude/skills/vercel-cli-with-tokens/SKILL.md
#   .claude/skills/vercel-cli-with-tokens/SKILL.md
# or any path the host's skill loader watches

The published GitHub release for this skill ships as a .skill artifact (zip with SKILL.md only — no scripts/ or references/ directory). Unzip into the same path if your host expects that layout.

Quick start

# install CLI
npm install -g vercel
vercel --version

# export token (never pass --token)
export VERCEL_TOKEN="vca_..."

# optional: skip .vercel/ directory entirely
export VERCEL_ORG_ID="team_..."
export VERCEL_PROJECT_ID="prj_..."

# preview deploy (the default — production needs an explicit ask)
vercel deploy -y --no-wait

# inspect
vercel inspect <deployment-url>

Gotchas

• Never vercel deploy --token "vca_...". Putting secrets in command-line arguments exposes them in shell history and process listings. The CLI reads VERCEL_TOKEN natively once it is exported.
• VERCEL_ORG_ID and VERCEL_PROJECT_ID must be set together. Setting only one causes an error, not a fallback.
• Do not run vercel project inspect or vercel link in an unlinked directory to detect state. They will interactively prompt or silently link as a side-effect. vercel ls is safe (in an unlinked directory it defaults to showing all deployments for the scope). vercel whoami is safe anywhere.
• Default is preview, not production. Only run vercel deploy --prod when the user explicitly asks for production.
• Ask before git push. The skill says so twice. Push triggers an automatic deploy — agents that push without approval can ship unreviewed code to a live preview URL.
• Do not modify .vercel/ files directly. The CLI manages this directory. Reading orgId from .vercel/project.json or .vercel/repo.json is fine.
• Do not curl/fetch deployed URLs to “verify” a deploy. The deploy is verified by vercel inspect <url>. Fetching a freshly deployed URL can hit a stale cache and produce a confusing error report. Just return the link.
• Stripe Projects plan changes bill a real card. Upgrades (stripe projects add vercel/pro) and downgrades (stripe projects downgrade vercel-plan hobby) are paid / destructive. Always ask before running.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not run a vercel deploy in the sandbox.

Related: Refactoring UI Audit — what to do once the deploy is live and the UI needs work; Frontend Design — net-new UI to ship to that Vercel project; Vercel Composition Patterns — for the React code shape inside the project being deployed.