前言¶
本地改完代码，下一步往往是上线验证：配环境、装 CLI、登录账号、选预览还是生产……对习惯用 AI 编程助手写代码的开发者来说，这些步骤常常打断心流。你更想要的是一句「帮我把这个项目部署出去，把链接给我」，Agent 就能按规范走完流程。
vercel-deploy 就是为此准备的 Agent Skill。它收录在 OpenAI 维护的 openai/skills 仓库 .curated 精选目录中，Skill 本身由 Vercel 授权（MIT License），专门指导 AI Agent 把应用或网站部署到 Vercel，并返回可访问的预览链接。下文基于官方 SKILL.md 与 scripts/deploy.sh 源码整理，关键流程均可对照原文核实。
这是什么¶
vercel-deploy 是一个通用格式的 Agent Skill（SKILL.md + 配套脚本），核心定位是：
当用户说「部署我的应用」「部署并给我链接」「推上线」或「创建预览部署」时，Agent 应调用此 Skill，把项目部署到 Vercel 并返回 URL。
它解决的不是「教你怎么写 Vercel 配置」，而是把部署动作标准化：Agent 先检查 Vercel CLI，能走 CLI 就走 CLI；CLI 不可用或未登录时，自动降级到 Skill 自带的 deploy.sh 脚本，无需用户事先配置 Vercel 账号也能拿到预览链接。
来源归属：
- 仓库：openai/skills →
skills/.curated/vercel-deploy/ - 版权：Vercel（MIT License，2026）
- 兼容工具：Cursor、Codex CLI、Claude Code 等支持
SKILL.md格式的 AI 编程工具
核心功能与亮点¶
1. 默认预览部署，避免误上生产¶
Skill 明确规定：除非用户明确要求生产环境，否则一律以预览（Preview）方式部署。这能避免 Agent 在用户只想「看看效果」时，误把未验证的代码推到 Production。
生产部署仅在用户显式要求时执行：
vercel deploy [path] --prod -y
2. 双路径部署：CLI 优先，脚本兜底¶
路径 A — Vercel CLI（已安装且已登录）
- 先用普通权限检查 CLI 是否存在（不提升沙箱权限）：
command -v vercel
- 若存在，执行部署（建议超时设为 10 分钟，构建可能较久）：
vercel deploy [path] -y
路径 B — 无认证兜底脚本
当 CLI 未安装，或报错 No existing credentials found 时，Agent 应调用 Skill 目录下的 scripts/deploy.sh：
skill_dir="<path-to-skill>"
# 部署当前目录
bash "$skill_dir/scripts/deploy.sh"
# 部署指定项目目录
bash "$skill_dir/scripts/deploy.sh" /path/to/project
# 部署已有 tarball
bash "$skill_dir/scripts/deploy.sh" /path/to/project.tgz
脚本会把项目打包上传到 https://codex-deploy-skills.vercel.sh/api/deploy，等待构建完成后返回 JSON，其中包含：
previewUrl：可直接访问的预览站点claimUrl：用于将部署认领到你自己的 Vercel 账号
Agent 应告知用户：「Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment.」
3. 自动框架检测与静态站点处理¶
deploy.sh 会读取 package.json 的依赖，自动识别框架类型，例如 Next.js、Nuxt、SvelteKit、Astro、Remix、Vite、Express、NestJS 等数十种。打包时会排除 node_modules、.git、.env 等目录，避免上传冗余或敏感文件。
对于没有 package.json 的纯静态 HTML 项目：若根目录只有一个 HTML 文件且不叫 index.html，脚本会自动将其重命名为 index.html，确保页面在根路径 / 可访问。
4. 沙箱网络与超时处理¶
在 Cursor、Codex 等沙箱环境中，部署可能因网络受限失败。Skill 要求：检查 CLI 时不要提升权限；仅在执行实际部署命令时，若出现超时、DNS 错误或连接重置，才用 sandbox_permissions=require_escalated 重试部署命令。部署本身可能耗时数分钟，Agent 需设置合理超时（CLI 路径建议 600000ms，即 10 分钟）。
5. 输出规范¶
- 向用户展示部署 URL；兜底脚本部署时同时展示 claim URL
- 不要用 curl 等方式去验证部署 URL 是否可访问，直接返回链接即可
安装与启用¶
Skill 以目录形式存在，至少需要 SKILL.md 与 scripts/deploy.sh（兜底部署依赖后者）。官方目录结构如下：
vercel-deploy/
├── SKILL.md
├── scripts/
│ └── deploy.sh
├── agents/
│ └── openai.yaml
├── assets/
├── LICENSE.txt
在 Cursor 中使用¶
- 从官方仓库复制整个
vercel-deploy目录到项目或用户级 Skills 路径：
# 项目级（随仓库共享给团队）
mkdir -p .cursor/skills
git clone --depth 1 --filter=blob:none --sparse https://github.com/openai/skills.git /tmp/openai-skills
cd /tmp/openai-skills && git sparse-checkout set skills/.curated/vercel-deploy
cp -r skills/.curated/vercel-deploy /你的项目/.cursor/skills/
# 或用户级（所有项目可用）
cp -r skills/.curated/vercel-deploy ~/.cursor/skills/
-
确认
SKILL.md顶部 frontmatter 包含name: vercel-deploy与description字段；文件夹名须与name一致（小写、连字符）。 -
重启或刷新 Cursor 后，Skill 会出现在 Agent 可用技能列表中。可在 Agent 对话里输入
/vercel-deploy手动调用，也可在描述匹配时由 Agent 自动选用。
Cursor 还会扫描 .agents/skills/ 与 ~/.agents/skills/，路径规则与 .cursor/skills/ 相同。
在 Codex CLI 中使用¶
将同样目录放到 .codex/skills/vercel-deploy/ 或 ~/.codex/skills/vercel-deploy/。Codex 默认运行在沙箱中，Skill 文档特别说明：先尝试 CLI，认证失败再回退到 deploy.sh。
在 Claude Code 中使用¶
放到 .claude/skills/vercel-deploy/ 或 ~/.claude/skills/vercel-deploy/，格式与 Cursor 一致。
典型用法示例¶
场景一：本地 Next.js 项目，CLI 已登录¶
用户对 Agent 说：
帮我把当前项目部署到 Vercel，把预览链接给我。
Agent 按 Skill 执行：
command -v vercel
vercel deploy . -y
返回形如 https://xxx.vercel.app 的预览 URL。
场景二：沙箱环境，无 Vercel 登录¶
用户对 Agent 说：
Deploy my app and give me the link.
CLI 报 No existing credentials found 后，Agent 调用：
bash "$skill_dir/scripts/deploy.sh" .
脚本 stderr 会输出构建进度，最终 stdout 返回 JSON。用户得到两个链接，例如：
- Preview URL：
https://skill-deploy-xxxxx.vercel.app - Claim URL：
https://vercel.com/claim-deployment?code=...
通过 Claim URL 可将该部署绑定到自己的 Vercel 账号，后续可在控制台管理域名、环境变量等。
场景三：明确要求生产部署¶
用户说：
把这个项目部署到 Vercel 生产环境。
此时 Agent 才应使用：
vercel deploy . --prod -y
若 CLI 不可用，需先与用户确认是否接受预览部署 + Claim 流程，因为兜底脚本面向的是可认领的预览部署，而非直接推 Production。
适用场景与注意事项¶
适合谁用
- 用 AI 助手快速搭原型、落地页、全栈 Demo，需要「改完即看线上效果」
- 在 Cursor / Codex / Claude Code 沙箱里开发，暂时无法或未配置 Vercel CLI 登录
- 团队希望把「部署到 Vercel」固化为 Agent 标准动作，减少口头重复指令
使用注意
- 预览优先：Skill 设计哲学是默认 Preview；生产部署必须用户明确开口。
- 保留 scripts 目录：仅复制
SKILL.md不够，无认证兜底依赖scripts/deploy.sh。 - 构建时间：首次部署可能较慢，Agent 与人都需耐心等待；脚本最多轮询约 5 分钟等待构建完成。
- 敏感文件：脚本会排除
.env等，但部署前仍建议检查项目中是否含不应上传的密钥。 - 网络权限：沙箱内部署失败时，Agent 可能需要你授权提升网络权限后重试。
- 与 Vercel 官方 Skill 的区别：Vercel Labs 也维护 deploy-to-vercel 等 Skill，流程更侧重 CLI 登录与 Git 关联；OpenAI 精选的 vercel-deploy 更突出「零账号预览 + Claim」兜底，适合 Agent 沙箱场景。
小结¶
vercel-deploy 把「从代码到可访问链接」这件事写进了 Agent 的可执行规范：CLI 能用时走标准 vercel deploy，不能用时用 bundled 脚本一键打包上传，返回预览 URL 与 Claim URL。对广泛采用 Vercel 做前端与全栈托管的开发者来说，这是实用面很广的一个 Skill。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/vercel-deploy
