Preface

When using AI coding tools like Cursor, Claude Code, or Codex to build Web projects, the common bottleneck is rarely writing code, but rather how to get the online preview effect as quickly as possible. Even if the project runs locally, you still need to configure Vercel CLI, log in, select a team, link the project, and decide whether to use git push or vercel deploy. Getting stuck on any of these steps will prevent you from getting the preview link.

The deploy-to-vercel Agent Skill is built exactly for this scenario: it固化s the workflow of “detect project status → select appropriate deployment path → return preview URL” into a reusable process. When you say “deploy this” or “give me a preview link”, the Agent will automatically follow the rules instead of cobbling together commands on the spot every time.

This article is compiled based on the SKILL.md (metadata version 3.0.0, author: vercel) from the official Vercel Labs repository vercel-labs/agent-skills and the installation instructions on skills.sh. The commands and branch logic are based on the first-hand official materials.

What is this

deploy-to-vercel is a deployment skill in Vercel’s official Agent Skills collection, following the universal SKILL.md format from Agent Skills. It can be installed and used in AI coding tools that support this format.

One-sentence positioning: When the user requests deployment, prioritize generating a Preview deployment, and strive to push the project to a long-term state of “already linked + ready for automatic deployment via git push”.

The official trigger scenarios include statements like:
- deploy my app
- deploy and give me the link
- push this live
- create a preview deployment

The default rule is clear: Always create a preview first, unless the user explicitly requests a production deployment.

Repository and documentation links:
- GitHub: https://github.com/vercel-labs/agent-skills/tree/main/skills/deploy-to-vercel
- skills.sh: https://skills.sh/vercel-labs/agent-skills/deploy-to-vercel

Core Capabilities

Combined with the official SKILL.md and skills.sh summary, this Skill mainly does the following things.

1. Detect status first, then choose deployment method
Before deployment, it runs a set of checks instead of running vercel deploy directly:
- Whether there is a git remote (specifically origin)
- Whether the project has been linked to a Vercel project via .vercel/project.json or .vercel/repo.json
- Whether the vercel CLI is installed and logged in (vercel whoami)
- If logged in, list available teams (vercel teams list --format json)

With this information, it will decide whether to use git push, direct CLI deployment, link first then deploy, or fall back to the sandbox unauthenticated script.

2. Three main deployment paths + sandbox fallback
skills.sh summarizes three types of deployment paths, consistent with SKILL.md:
- Already linked + has git remote: Use git push (ideal state, subsequent pushes will automatically trigger deployments)
- Already linked + no git remote: Run vercel deploy … -y --no-wait
- Not linked / not logged in: First install the CLI, log in, link with team scope, then deploy
- Sandbox environment unable to log in: Use resources/deploy.sh (for claude.ai) or resources/deploy-codex.sh (for Codex), which can get the Preview URL and Claim URL without an account

3. Use --scope for multiple teams, respect local org if already linked
If you have multiple teams under your account, it will list the slugs for you to select once. Subsequent vercel deploy / vercel link / vercel inspect commands will carry the --scope <team-slug> parameter. If there is already a .vercel/ configuration locally, the orgId inside will be used as the standard, and no repeated questions will be asked.

4. The output is always a clickable deployment link
- git push: When the CLI is logged in, use vercel ls --format json to get the url of the latest deployment from the deployments list
- CLI deploy: Directly display the URL returned by vercel deploy --no-wait, then use vercel inspect to check the build status
- Unauthenticated fallback: Provide both the Preview URL and the Claim URL (to claim the deployment to your own Vercel account)

The official also emphasizes: Do not use curl/fetch to “verify” whether the online page is available; just hand the link to the user.

Installation and Enablement

The command to install a single skill via skills.sh is:

npx skills add https://github.com/vercel-labs/agent-skills --skill deploy-to-vercel

If you want to install the entire vercel-labs/agent-skills collection, the official README also provides:

npx skills add vercel-labs/agent-skills

After installation, the Agent will load this Skill when matching deployment-related intentions. The skill directory mainly contains:
- SKILL.md: Complete decision and command instructions for the Agent
- resources/deploy.sh: Unauthenticated deployment script for scenarios like claude.ai
- resources/deploy-codex.sh: Unauthenticated deployment script for Codex sandbox

SKILL.md has separate instructions for paths in some runtime environments (please refer to your actual local installation location):
- Claude Code / terminal-based Agents: Do not use the /mnt/skills/ path, follow the CLI decision flow directly; for unauthenticated fallback, run a command similar to
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
- claude.ai sandbox: Usually unable to vercel login / git push, directly use the no-auth fallback
- Codex: First check the CLI, fall back to deploy-codex.sh if it fails

This Skill is based on the universal SKILL.md format; tools that support Agent Skills such as Cursor, Codex CLI, and Claude Code can use it in principle. If the official does not hardcode the local skill directory path for each tool, please refer to the installation result of the tool you are using, and no additional fabricated paths will be provided here.

Decision Flow and Typical Usage

1. Pre-deployment status check

The official requires completing all checks before selecting a deployment method, for example:

# 1. git remote
git remote get-url origin 2>/dev/null

# 2. Check if already linked (either file exists)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. Check if CLI is logged in
vercel whoami 2>/dev/null

# 4. List available teams
vercel teams list --format json 2>/dev/null

About .vercel/:
- .vercel/project.json: Generated by vercel link, contains projectId and orgId
- .vercel/repo.json: Generated by vercel link --repo, contains orgId, remoteName and the mapping from directory to project ID

Do not use vercel project inspect, vercel ls, or vercel link in unlinked directories for “detection” — they may pop up interactive prompts, or silently link when using --yes. The officially recommended safe way to detect login status is vercel whoami.

2. Already linked and has git remote: Prioritize git push

This is the long-term recommended state. Key process points:
1. You must get user consent before pushing; do not push without authorization.
2. After the user agrees, run git add / commit / push; non-production branches usually get a preview deployment, while production branches (usually main) correspond to production environments.
3. When the CLI is logged in, wait a moment then use vercel ls --format json to get the url of the latest deployment from the deployments list.

Example:

git add .
git commit -m "deploy: <description of changes>"
git push

sleep 5
vercel ls --format json

3. Already linked but no git remote: Direct CLI deployment

vercel deploy [path] -y --no-wait
vercel inspect <deployment-url>

The role of --no-wait is to return the deployment URL immediately, preventing the Agent from getting stuck during the long build process; hand over the build progress to vercel inspect.

Only when the user explicitly requests a production environment:

vercel deploy [path] --prod -y --no-wait

For multiple teams, add the scope parameter, for example:

vercel deploy [path] -y --no-wait --scope <team-slug>

If there is a git remote, prioritize repo-level link (matches the remote repository, which is more stable than matching by directory name):

vercel link --repo --scope <team-slug>

If there is no git remote:

vercel link --scope <team-slug>

After linking: If there is a remote, follow the git push process (still requires user confirmation); if there is no remote, run vercel deploy … --no-wait.

5. No CLI installed / not logged in at all

The official step sequence is: npm install -g vercel → vercel login (complete authentication in the browser) → select a team → link → deploy according to the rules above. If the environment cannot perform interactive login, enter the unauthenticated fallback mode.

6. Unauthenticated fallback (sandbox)

Example for claude.ai:

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz

For Codex when the CLI is unavailable or reports “No existing credentials found”:

bash "$skill_dir/resources/deploy-codex.sh"
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project

The script will automatically detect the framework, package the project (exclude node_modules, .git, .env, etc.), upload it and wait for the build to complete, then return the Preview URL and Claim URL. The standard feedback format for users is similar to:

Deployment successful!

Preview URL: https://my-app-abc123.vercel.app
Claim URL:   https://vercel.com/claim-deployment?code=...

View your site at the Preview URL.
To transfer this deployment to your Vercel account, visit the Claim URL.

How to Talk to the Agent

After installation and enablement, you can trigger it with natural language, for example:

Deploy the current project to Vercel and give me the preview link.

Create a preview deployment, do not deploy to production.

This project is already linked to Vercel, help me commit and push to trigger deployment (ask me first before pushing).

If you have multiple teams, the Agent should list the team slugs as required by the Skill, and you can select one to continue. You do not need to confirm “whether to link” a second time in the middle.

Applicable Scenarios and Notes

Most suitable for:
- Next.js / frontend / full-stack Web projects that need to quickly get a Preview URL
- Closing the delivery loop of “write code with AI and get a demo link”
- Projects that already have or are preparing to set up Vercel + Git integration, and hope the Agent can push the project to a state of sustainable automatic deployment
- Temporary demos in claude.ai / Codex sandboxes, then claim the deployment to your own account using the Claim URL later

Things to note:
- Deployment by default is not production release; --prod is only used when you explicitly request it.
- You must get user consent before git push; the Skill writes this as a hard constraint.
- Do not use CLI commands with side effects for “detection” in unlinked directories.
- If the sandbox has network restrictions: claude.ai needs to allow *.vercel.com in capabilities; Codex only grants network privileges for actual deployment commands, not checks like command -v vercel.
- When CLI authentication fails, fall back to the corresponding no-auth script according to the environment instead of repeatedly trying to log in.
- Unauthenticated deployment is a temporary ownership model that can be claimed; for long-term management, it is recommended to use a formal account + link + Git integration.

Summary

deploy-to-vercel turns scattered Vercel deployment commands into a state machine that can be executed by an Agent: first check git, .vercel, CLI, and teams, then select git push, CLI deployment, or sandbox script, and fix the Preview URL (plus Claim URL if necessary) as the deliverable. For workflows where “write code with AI and open the link immediately”, it makes up the final mile.

Official links:
- https://github.com/vercel-labs/agent-skills/tree/main/skills/deploy-to-vercel
- https://skills.sh/vercel-labs/agent-skills/deploy-to-vercel