305 lines
12 KiB
Markdown
305 lines
12 KiB
Markdown
---
|
|
name: deploy-to-vercel
|
|
description: "Deploy applications and websites to Vercel. Use when the user requests deployment actions like \"deploy my app\", \"deploy and give me the link\", \"push this live\", or \"create a preview deployment\"."
|
|
risk: safe
|
|
source: "https://github.com/vercel-labs/agent-skills"
|
|
date_added: "2026-06-02"
|
|
---
|
|
|
|
# Deploy to Vercel
|
|
|
|
Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
|
|
|
|
The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
|
|
|
|
## When to Use
|
|
- Use this skill when the task matches this description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
|
|
|
|
## Step 1: Gather Project State
|
|
|
|
Run all four checks before deciding which method to use:
|
|
|
|
```bash
|
|
# 1. Check for a git remote
|
|
git remote get-url origin 2>/dev/null
|
|
|
|
# 2. Check if locally linked to a Vercel project (either file means linked)
|
|
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
|
|
|
|
# 3. Check if the Vercel CLI is installed and authenticated
|
|
vercel whoami 2>/dev/null
|
|
|
|
# 4. List available teams (if authenticated)
|
|
vercel teams list --format json 2>/dev/null
|
|
```
|
|
|
|
### Team selection
|
|
|
|
If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
|
|
|
|
Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
|
|
|
|
```bash
|
|
vercel deploy [path] -y --no-wait --scope <team-slug>
|
|
```
|
|
|
|
If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
|
|
|
|
**About the `.vercel/` directory:** A linked project has either:
|
|
- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
|
|
- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
|
|
|
|
Either file means the project is linked. Check for both.
|
|
|
|
**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
|
|
|
|
## Step 2: Choose a Deploy Method
|
|
|
|
### Linked (`.vercel/` exists) + has git remote → Git Push
|
|
|
|
This is the ideal state. The project is linked and has git integration.
|
|
|
|
1. **Ask the user before pushing.** Never push without explicit approval:
|
|
```
|
|
This project is connected to Vercel via git. I can commit and push to
|
|
trigger a deployment. Want me to proceed?
|
|
```
|
|
|
|
2. **Commit and push:**
|
|
```bash
|
|
git add .
|
|
git commit -m "deploy: <description of changes>"
|
|
git push
|
|
```
|
|
Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
|
|
|
|
3. **Retrieve the preview URL.** If the CLI is authenticated:
|
|
```bash
|
|
sleep 5
|
|
vercel ls --format json
|
|
```
|
|
The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
|
|
|
|
If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
|
|
|
|
---
|
|
|
|
### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
|
|
|
|
The project is linked but there's no git repo. Deploy directly with the CLI.
|
|
|
|
```bash
|
|
vercel deploy [path] -y --no-wait
|
|
```
|
|
|
|
Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
|
|
|
|
```bash
|
|
vercel inspect <deployment-url>
|
|
```
|
|
|
|
For production deploys (only if user explicitly asks):
|
|
```bash
|
|
vercel deploy [path] --prod -y --no-wait
|
|
```
|
|
|
|
---
|
|
|
|
### Not linked + CLI is authenticated → Link first, then deploy
|
|
|
|
The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
|
|
|
|
1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
|
|
|
|
2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
|
|
```
|
|
Linking this project to <team name> on Vercel. This will create a Vercel
|
|
project to deploy to and enable automatic deployments on future git pushes.
|
|
```
|
|
|
|
3. **If a git remote exists**, use repo-based linking with the selected team scope:
|
|
```bash
|
|
vercel link --repo --scope <team-slug>
|
|
```
|
|
This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
|
|
|
|
**If there is no git remote**, fall back to standard linking:
|
|
```bash
|
|
vercel link --scope <team-slug>
|
|
```
|
|
This prompts the user to select or create a project. It creates `.vercel/project.json`.
|
|
|
|
4. **Then deploy using the best available method:**
|
|
- If a git remote exists → commit and push (see git push method above)
|
|
- If no git remote → `vercel deploy [path] -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status
|
|
|
|
---
|
|
|
|
### Not linked + CLI not authenticated → Install, auth, link, deploy
|
|
|
|
The Vercel CLI isn't set up at all.
|
|
|
|
1. **Install the CLI (if not already installed):**
|
|
```bash
|
|
npm install -g vercel
|
|
```
|
|
|
|
2. **Authenticate:**
|
|
```bash
|
|
vercel login
|
|
```
|
|
The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
|
|
|
|
3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
|
|
|
|
4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
|
|
```bash
|
|
vercel link --repo --scope <team-slug> # if git remote exists
|
|
vercel link --scope <team-slug> # if no git remote
|
|
```
|
|
|
|
5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status).
|
|
|
|
---
|
|
|
|
### No-Auth Fallback — claude.ai sandbox
|
|
|
|
**When to use:** Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
|
|
|
|
```bash
|
|
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
|
|
```
|
|
|
|
**Arguments:**
|
|
- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Deploy current directory
|
|
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
|
|
|
|
# Deploy specific project
|
|
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
|
|
|
|
# Deploy existing tarball
|
|
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
|
|
```
|
|
|
|
The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
|
|
|
|
**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
|
|
|
|
---
|
|
|
|
### No-Auth Fallback — Codex sandbox
|
|
|
|
**When to use:** In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.
|
|
|
|
1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
|
|
```bash
|
|
command -v vercel
|
|
```
|
|
|
|
2. **If `vercel` is installed**, try deploying with the CLI:
|
|
```bash
|
|
vercel deploy [path] -y --no-wait
|
|
```
|
|
|
|
3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
|
|
```bash
|
|
skill_dir="<path-to-skill>"
|
|
|
|
# Deploy current directory
|
|
bash "$skill_dir/resources/deploy-codex.sh"
|
|
|
|
# Deploy specific project
|
|
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
|
|
|
|
# Deploy existing tarball
|
|
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
|
|
```
|
|
|
|
The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
|
|
|
|
**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
|
|
|
|
**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
|
|
|
|
---
|
|
|
|
## Agent-Specific Notes
|
|
|
|
### Claude Code / terminal-based agents
|
|
|
|
You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
|
|
|
|
For the no-auth fallback, run the deploy script from the skill's installed location:
|
|
```bash
|
|
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
|
|
```
|
|
The path may vary depending on where the user installed the skill.
|
|
|
|
### Sandboxed environments (claude.ai)
|
|
|
|
You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — claude.ai sandbox**.
|
|
|
|
### Codex
|
|
|
|
Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Codex sandbox**.
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
Always show the user the deployment URL.
|
|
|
|
- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
|
|
- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect <url>` to check build status and report it to the user.
|
|
- **No-auth fallback:** Show both the preview URL and the claim URL:
|
|
```
|
|
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.
|
|
```
|
|
|
|
**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Network Egress Error (claude.ai)
|
|
|
|
If deployment fails due to network restrictions on claude.ai, tell the user:
|
|
|
|
```
|
|
Deployment failed due to network restrictions. To fix this:
|
|
|
|
1. Go to https://claude.ai/settings/capabilities
|
|
2. Add *.vercel.com to the allowed domains
|
|
3. Try deploying again
|
|
```
|
|
|
|
### Escalated Network Access (Codex / sandboxed environments)
|
|
|
|
If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
|
|
|
|
Example guidance to the user:
|
|
```
|
|
The deploy needs escalated network access to deploy to Vercel. I can rerun
|
|
the command with escalated permissions — want me to proceed?
|
|
```
|
|
|
|
### CLI Auth Failure
|
|
|
|
If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).
|
|
|
|
## Limitations
|
|
- Use this skill only when the task clearly matches the scope described above.
|
|
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
|
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|