前言¶

用 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