vercel-labs/skills 保姆级部署教程：npx skills 一键安装开源 Agent 技能
一句话定位：Vercel Labs 出品的开源 CLI 工具
vercel-labs/skills——它是「开源 Agent 技能生态」的统一入口，一条npx skills命令就能在 Claude Code、Codex、Cursor、OpenCode 等 79 个编码智能体之间搜索、安装、更新、卸载可复用的技能（SKILL.md 指令包），把社区沉淀的最佳实践直接装进你正在用的 AI 编程助手。slogan：The CLI for the open agent skills ecosystem. Discover skills at skills.sh.
仓库地址：https://github.com/vercel-labs/skills · 许可证：MIT · ⭐ 37,428 · npm 包名
skills
▲ 图 0：vercel-labs/skills 官方 README 顶部展示的 Vercel Labs 出品徽标与 skills.sh 收录徽标（官方截图）
一、项目简介
Agent Skill（智能体技能）是一份可复用的指令包，通常是一个带 frontmatter 的 SKILL.md 文件，用来教编码智能体如何完成某一类任务——从代码评审、写测试，到如何调用某个具体库、如何遵循某套团队规范。过去这些指令散落在各个项目的 prompt 片段里，谁都可以写，但没有统一的分发渠道。
vercel-labs/skills 就是 Vercel Labs 为这个生态做的「包管理器」。它本身不教智能体做事，它负责把技能从 GitHub 仓库（或 npm 包）拉下来，按你本机安装的编码智能体类型，写到对应目录里——Claude Code 写到 .claude/skills/，Codex 写到对应目录，Cursor、OpenCode 同理。一条命令同时支持 79 个智能体（README 明确列出 OpenCode、Claude Code、Codex、Cursor，另加 75 个），由 CLI 自动探测你本机装了哪些 agent。
项目以 MIT 许可证开源，当前在 npm 上发布的包名就是 skills，无需全局安装，直接 npx skills 即可运行；技能目录站在 skills.sh，技能格式规范由 agentskills.io 维护。
二、功能特点
| 能力 | 说明 |
|---|---|
| 📦 一条命令安装 | npx skills add <owner/repo> 即可从 GitHub 仓库拉取技能，交互式选择技能与目标 agent，无需 clone、无需手动复制目录 |
| 🤖 79 个智能体兼容 | 支持 OpenCode、Claude Code、Codex、Cursor 等，CLI 自动探测本机已装 agent 并写到对应技能目录；完整清单见 docs/agents.md |
| 🔍 技能搜索 | npx skills find [query] 按关键词在技能目录中检索，配合 skills.sh 浏览 |
| 🌍 项目级 / 全局级 | 默认装到当前项目；加 -g 标志装成全局可用，跨项目共享 |
| 🚀 免安装试用 | npx skills use <source>@<skill> 直接为某个技能生成 prompt 或启动带该技能的 agent，不落盘 |
| 🔄 更新与卸载 | npx skills check 查更新、npx skills update 升级、npx skills remove 卸载、npx skills list 列已装 |
| 🧩 自建技能模板 | npx skills init my-skill 生成带 frontmatter 的 SKILL.md 模板，按格式写完即可发布到 skills.sh |
| 📦 npm 包内嵌技能（实验） | npx skills experimental_sync 把 npm 依赖里附带的 agent 指令同步进项目，跟随依赖版本一起升级 |
| 🔒 无侵入、可审计 | 技能就是 SKILL.md 文件，装在哪、写了什么全部可见；telemetry 可用 DISABLE_TELEMETRY=1 关闭 |
| ⚡ 免全局安装 | 基于 npx 运行，不污染全局环境；每次拉取最新版 CLI |
三、环境要求
- Node.js 版本：README 明确要求 Node.js 22.20 或更高版本（这是硬性要求，低版本会直接报错）。用
node -v自检。 - npm / npx：随 Node 一起安装，无需额外配置；能访问 npm registry 即可。
- 网络：需要能访问 GitHub（拉技能仓库）与 npm registry（拉 CLI 本身）；国内网络建议配好镜像或代理。
- 已安装至少一个编码智能体：技能最终要落到某个 agent 的目录里，本机至少装一个（Claude Code、Codex、Cursor、OpenCode 等）；只做技能浏览也可以不装。
- 操作系统：macOS / Linux / Windows（WSL 或原生）均可，CLI 是跨平台 Node 脚本。
四、保姆级部署步骤
4.1 准备 Node.js 22.20+
先确认本机 Node 版本，低于 22.20 请用 nvm / fnm / 官网安装包升级：
node -v
# 期望输出 v22.20.0 或更高，例如 v24.0.0
# 如果用 nvm 管理，升级到最新 LTS：
nvm install 22
nvm use 224.2 一条命令安装第一个技能
进入你自己的项目目录（任意 git 仓库或空目录都行），执行：
cd your-project
npx skills add vercel-labs/agent-skills第一次运行 npx 会提示安装 skills 这个包，回车确认即可。随后 CLI 会：
- 从 vercel-labs/agent-skills 拉取技能清单；
- 交互式让你勾选要装哪些技能（方向键 + 空格多选）；
- 自动探测本机装了哪些编码智能体（Claude Code / Codex / Cursor / OpenCode…），让你勾选装到哪个；
- 把选定的
SKILL.md写到对应目录，完成。
想跳过交互、直接指定技能和 agent，用参数：
# 只装 web-design-guidelines 这一个技能，只装到 claude-code
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code
# 装成全局技能（跨项目可用）
npx skills add vercel-labs/agent-skills -g4.3 浏览与搜索技能
# 交互式浏览当前可发现的技能
npx skills find
# 按关键词搜索，例如找和「review」相关的技能
npx skills find review也可以直接打开技能目录站 skills.sh，在网页上按分类、按仓库浏览，找到心仪的技能后把它的 owner/repo 记下来，回到终端 npx skills add owner/repo。
4.4 查看已装技能 / 更新 / 卸载
# 列出当前项目已装的所有技能
npx skills list
# 检查哪些技能有新版本可用
npx skills check
# 更新指定技能（不带参数则更新全部）
npx skills update
npx skills update web-design-guidelines
# 卸载技能
npx skills remove web-design-guidelines4.5 免安装试用某个技能
不想落盘、只想看一眼这个技能会给 agent 注入什么 prompt，或临时跑一次：
# 只打印 prompt，不启动 agent
npx skills use vercel-labs/agent-skills@web-design-guidelines
# 直接带着这个技能启动 claude-code
npx skills use vercel-labs/agent-skills@web-design-guidelines --agent claude-code4.6 自己写一个技能并发布
# 生成技能模板
npx skills init my-skill
# 编辑生成的 SKILL.md（带 YAML frontmatter：name、description 等）
# 写完后 push 到 GitHub 仓库，即可通过 skills.sh 被他人发现
技能格式与 frontmatter 字段、仓库布局规则，详见 docs/creating-skills.md。
五、配置说明
- 安装位置：默认装到当前项目下对应 agent 的技能目录（如
.claude/skills/）；加-g装到用户级目录，所有项目共享。 - 私有仓库：
npx skills add支持从私有 GitHub 仓库拉取，前提是本机已配置好ghCLI 或 git 凭据；完整 source 格式见 docs/commands.md。 - Telemetry 关闭：CLI 默认收集匿名使用数据，设置环境变量即可关闭：
export DISABLE_TELEMETRY=1 # 或 export DO_NOT_TRACK=1 - npm 包内嵌技能（实验）：如果某个 npm 包在
package.json里声明了skills字段，npx skills experimental_sync会把它们链接进项目，跟随依赖一起升级：npm install -D skills agent-browser npx skills experimental_sync -y - 锁定文件：
skills-lock.json记录项目已装技能清单，npx skills experimental_install可按锁文件恢复，适合团队协作与 CI。
六、使用方法
装好技能后，不需要在终端里再调用任何 skills 命令——技能已经作为 SKILL.md 躺在编码智能体的技能目录里。你平时怎么用 Claude Code / Codex / Cursor，就怎么用：
- 正常启动你的编码智能体（例如
claude、codex、Cursor 里打开项目）。 - 在对话里触发对应任务，agent 会自动加载匹配的技能指令（例如装了
web-design-guidelines后，让它写前端页面时会自动套用那套设计规范）。 - 技能是「按需加载」的：frontmatter 里的
description决定 agent 什么时候想起它，不是每次都全量注入 prompt。 - 想确认某个技能生效没有，直接打开
.claude/skills/<skill-name>/SKILL.md看内容即可，全部是纯文本，可审计。
团队协同时，把 skills-lock.json 提交进 git，同事 clone 后跑一次 npx skills experimental_install（或重新 npx skills add），就能拿到和你完全一致的技能集合。
七、常见问题 FAQ
问一：npx skills 跑起来直接报 Node 版本太低怎么办？
答：README 硬性要求 Node.js 22.20 或更高。先 node -v 看版本，低了用 nvm / fnm 升级到 22 LTS 或最新版。不要尝试用旧 Node 强行跑，CLI 内部用了新语法，低版本会在 require 阶段就崩。
问二：装完之后，我的 Claude Code / Codex 里怎么没看到这个技能？
答：先确认你 npx skills add 时勾选了正确的目标 agent——CLI 会同时探测本机所有已装 agent，让你多选，漏勾就不会写进去。用 npx skills list 看当前项目装到了哪几个 agent；再去对应 agent 的技能目录（如 .claude/skills/）确认 SKILL.md 文件真实存在。最后重启一次编码智能体，让它重新扫描技能目录。
问三：技能是每次对话都全量塞进 prompt 吗？会不会很费 token？
答：不会。技能采用「按需加载」模型：每个 SKILL.md 的 frontmatter 里有 description，agent 根据任务上下文判断要不要加载这份指令，匹配上才注入。装 10 个技能不等于每次都带 10 份长 prompt。
问四：国内网络拉 GitHub 技能很慢或失败怎么办？
答：npx skills 本质是从 GitHub 仓库拉文件，可通过给 git 配代理、或使用 GitHub 镜像加速；npm 本身建议切国内镜像（如 npmmirror）。私有仓库场景确保本机 gh auth login 已完成。
问五：我能不能自己写一个技能发到 skills.sh 让别人用？
答：可以，这正是这个项目的设计目标。跑 npx skills init my-skill 生成模板，编辑 SKILL.md（YAML frontmatter + 正文指令），push 到你的 GitHub 仓库，然后按 creating-skills.md 里的提交流程把仓库登记到 skills.sh。任何人之后就能 npx skills add your-name/your-skill 装上。
相关链接
- 项目仓库：vercel-labs/skills
- npm 包：skills on npm
- 技能目录站：skills.sh
- 技能格式规范：agentskills.io
- Vercel 官方技能集：vercel-labs/agent-skills
- CLI 命令参考：docs/commands.md
- 支持的智能体清单：docs/agents.md
- 自建技能指南：docs/creating-skills.md
- 排障与配置：docs/troubleshooting.md