前言¶

用 Cursor、Claude Code、Codex 这类 AI 编程工具写 Web 项目时，常见卡点往往不在写代码，而在「怎么尽快看到线上效果」。本地跑起来了，还要配 Vercel CLI、登录、选团队、link 项目、决定是 git push 还是 vercel deploy，中间随便一步卡住，预览链接就出不来。

deploy-to-vercel 正是为这件事准备的 Agent Skill：把「探测项目状态 → 选合适部署路径 → 返回预览 URL」固化成可复用的流程，让 Agent 在你说「部署一下」「给我个预览链接」时，按规则自动走完，而不是每次现场现编命令。

本文基于 Vercel Labs 官方仓库 vercel-labs/agent-skills 中的 SKILL.md（metadata 版本 3.0.0，author: vercel）以及 skills.sh 上的安装说明整理，命令与分支逻辑以一手资料为准。

这是什么¶

deploy-to-vercel 是 Vercel 官方 Agent Skills 集合里的一个部署技能，遵循通用的 Agent Skills 的 SKILL.md 格式，可在支持该格式的 AI 编程工具中安装使用。

一句话定位：在用户要求部署时，优先产出 Preview 部署，并尽量把项目推进到「已 link + 可 git push 自动部署」的长期状态。

官方描述里给出的触发场景包括类似这些说法：

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

默认规则很明确：始终先做 preview，除非用户明确要求 production。

仓库与文档入口：

• 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

核心能力¶

结合官方 SKILL.md 与 skills.sh 摘要，这个 Skill 主要做这几件事。

1. 先探测状态，再选部署方式

部署前会跑一组检查，而不是一上来就 vercel deploy：

• 是否有 git remote（origin）
• 是否已通过 .vercel/project.json 或 .vercel/repo.json 与 Vercel 项目关联
• vercel CLI 是否已安装且已登录（vercel whoami）
• 若已登录，列出可用团队（vercel teams list --format json）

有了这些信息，再决定走 git push、CLI 直推、先 link 再部署，还是沙箱无鉴权回退脚本。

2. 三条主路径 + 沙箱回退

skills.sh 概括为三类部署路径，与 SKILL.md 一致：

• 已 link + 有 git remote：走 git push（理想态，后续推送可自动触发部署）
• 已 link + 无 git remote：vercel deploy … -y --no-wait
• 未 link / 未登录：先安装 CLI、登录、按团队 scope link，再部署
• 沙箱环境无法登录：使用 resources/deploy.sh（claude.ai）或 resources/deploy-codex.sh（Codex），无需账号即可拿到 Preview URL 与 Claim URL

3. 多团队用 --scope，已 link 则尊重本地 org

若账号下有多个 team，会列出 slug 让你选一次，后续 vercel deploy / vercel link / vercel inspect 都带 --scope <team-slug>。若本地已有 .vercel/ 配置，则以其中的 orgId 为准，不再反复询问。

4. 输出始终是可点的部署链接

• git push：在 CLI 已登录时用 vercel ls --format json 取最新部署的 url
• CLI deploy：直接展示 vercel deploy --no-wait 返回的 URL，再用 vercel inspect 看构建状态
• 无鉴权回退：同时给出 Preview URL 和 Claim URL（把部署认领到自己的 Vercel 账号）

官方还强调：不要用 curl/fetch 去「验证」线上页面是否可用，把链接交给用户即可。

安装与启用¶

skills.sh 给出的按技能安装命令为：

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

若要安装整个 vercel-labs/agent-skills 集合，官方 README 也提供了：

npx skills add vercel-labs/agent-skills

安装后，Agent 在匹配到部署类意图时会加载该 Skill。技能目录里主要包含：

• SKILL.md：给 Agent 的完整决策与命令说明
• resources/deploy.sh：claude.ai 等场景的无鉴权部署脚本
• resources/deploy-codex.sh：Codex 沙箱用的无鉴权部署脚本

SKILL.md 里对部分运行环境的路径有单独说明（以你本机实际安装位置为准）：

• Claude Code / 终端类 Agent：不要走 /mnt/skills/，直接按 CLI 决策流；无鉴权回退时可执行类似
  bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
• claude.ai 沙箱：通常无法 vercel login / git push，直接走 no-auth 回退
• Codex：先查 CLI，失败再回退到 deploy-codex.sh

该 Skill 基于通用 SKILL.md 格式；Cursor、Codex CLI、Claude Code 等支持 Agent Skills 的工具原则上都能用。各工具的本地技能目录若官方未单独写死，以你所用工具的安装结果为准，这里不额外编造路径。

决策流程与典型用法¶

1. 部署前的状态检查¶

官方要求在选方法之前跑齐检查，例如：

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

# 2. 是否已 link（两个文件任一存在即可）
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. CLI 是否已登录
vercel whoami 2>/dev/null

# 4. 可用团队
vercel teams list --format json 2>/dev/null

关于 .vercel/：

• .vercel/project.json：vercel link 生成，含 projectId、orgId
• .vercel/repo.json：vercel link --repo 生成，含 orgId、remoteName 以及目录到项目 ID 的映射

不要在未 link 的目录里用 vercel project inspect、vercel ls、vercel link 来「探测」——它们可能弹出交互，或在 --yes 时静默 link。探测登录状态时，官方认为相对安全的是 vercel whoami。

2. 已关联且有 git remote：优先 git push¶

这是长期推荐状态。流程要点：

1. 推送前必须征得用户同意，不能擅自 push。
2. 用户同意后再 git add / commit / push；非生产分支通常得到 preview，生产分支（多为 main）对应 production。
3. CLI 已登录时，稍等后用 vercel ls --format json，从 deployments 里取最新一条的 url。

示意：

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

sleep 5
vercel ls --format json

3. 已关联但没有 git remote：CLI 直推¶

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

--no-wait 的作用是立刻返回部署 URL，避免 Agent 卡在漫长构建上；构建进度再交给 vercel inspect。

仅当用户明确要求生产环境时：

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

多团队时带上 scope，例如：

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

4. 未关联但 CLI 已登录：先 link，再部署¶

有 git remote 时优先 repo 级 link（按远程仓库匹配，比按目录名匹配更稳）：

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

没有 git remote 时：

vercel link --scope <team-slug>

link 完成后：有 remote 就走 git push（仍需用户确认）；没有 remote 就 vercel deploy … --no-wait。

5. 完全没 CLI / 未登录¶

官方步骤顺序是：npm install -g vercel → vercel login（浏览器完成鉴权）→ 选团队 → link → 再按上面规则部署。若环境无法交互登录，则进入无鉴权回退。

6. 无鉴权回退（沙箱）¶

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

Codex 在 CLI 不可用或报 “No existing credentials found” 时：

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

脚本侧会做框架探测、打包（排除 node_modules、.git、.env 等）、上传并等待构建，返回 Preview URL 与 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.

你可以怎么对 Agent 说¶

安装启用后，用自然语言触发即可，例如：

把当前项目部署到 Vercel，给我预览链接。

创建一次 preview deployment，不要上生产。

这个项目已经连过 Vercel，帮我 commit 并 push 触发部署（先问我再 push）。

若你有多个团队，Agent 应按 Skill 要求先列出 team slug，你选一个后再继续，中间不必二次确认「要不要 link」。

适用场景与注意事项¶

比较适合：

• Next.js / 前端 / 全栈 Web 项目要快速出 Preview URL
• AI 写完代码后要形成「可演示链接」的交付闭环
• 本地已有或准备建立 Vercel + Git 集成，希望 Agent 把项目推到可持续自动部署的状态
• 在 claude.ai / Codex 沙箱里临时演示，之后再用 Claim URL 认领到自己账号

需要留意：

• 默认不是生产发布；--prod 仅在你明确要求时使用。
• git push 前必须征得同意；Skill 把这一点写成硬约束。
• 未 link 目录里不要用会副作用的 CLI「探测」命令。
• 沙箱网络受限时：claude.ai 需在 capabilities 里放行 *.vercel.com；Codex 侧仅对真正的部署命令做网络提权，不要对 command -v vercel 这类检查提权。
• CLI 鉴权失败时，按环境回退到对应的 no-auth 脚本，而不是反复死磕登录。
• 无鉴权部署是「可认领」的临时归属模型，长期管理仍建议走正式账号 + link + git 集成。

小结¶

deploy-to-vercel 把 Vercel 部署从零散命令收成一套可给 Agent 执行的状态机：先看 git / .vercel / CLI / 团队，再选 git push、CLI deploy 或沙箱脚本，并固定以 Preview URL（必要时加 Claim URL）作为交付物。对「AI 写完就要能打开链接」的工作流来说，它补的是最后一公里。

官方地址：

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