🚀 一文掌握 Vercel Skills CLI：为你的 AI 编程助手赋能

前言：在 AI 编程时代，如何让 Claude Code、Cursor、Codex 等助手更懂你的业务？vercel-labs/skills 提供了一个优雅的解决方案——通过可复用的「技能包」扩展 AI 能力。本文将带你从零开始，全面掌握这个强大的 CLI 工具。

---

📦 项目简介

vercel-labs/skills 是一个开源的 Agent Skills 管理 CLI 工具，由 Vercel Labs 维护。它的核心价值是：

🔹 统一管理：为 40+ 种 AI 编程助手安装/管理技能包
🔹 即插即用：通过 SKILL.md 定义可复用的指令集
🔹 跨平台兼容：遵循统一的 Agent Skills 规范
🔹 生态丰富：官方 + 社区技能库持续更新

🔗 项目地址：https://github.com/vercel-labs/skills
🌐 技能市场：https://skills.sh

---

⚡ 快速开始

安装方式（无需全局安装）

# 直接使用 npx 运行（推荐）
npx skills add vercel-labs/agent-skills

# 或全局安装（可选）
npm install -g @vercel-labs/skills

支持的源码格式

# GitHub 简写（最常用）
npx skills add vercel-labs/agent-skills

# 完整 GitHub URL
npx skills add https://github.com/vercel-labs/agent-skills

# 指定子目录中的技能
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# GitLab 仓库
npx skills add https://gitlab.com/org/repo

# SSH Git 地址
npx skills add git@github.com:vercel-labs/agent-skills.git

# 本地路径
npx skills add ./my-local-skills

---

🛠️ 核心命令详解

🔹 安装技能：skills add

# 基础用法：安装仓库中的所有技能
npx skills add vercel-labs/agent-skills

# 只安装特定技能
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator

# 技能名含空格时需加引号
npx skills add owner/repo --skill "Convex Best Practices"

# 指定目标 Agent（支持多个）
npx skills add vercel-labs/agent-skills -a claude-code -a opencode

# 全局安装（对所有项目生效）
npx skills add vercel-labs/agent-skills --global

# 非交互式安装（适合 CI/CD）
npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y

# 一键安装所有技能到所有 Agent
npx skills add vercel-labs/agent-skills --all

# 安装所有技能到指定 Agent
npx skills add vercel-labs/agent-skills --skill '*' -a claude-code

📋 add 命令选项速查

选项	说明	示例
-g, --global	安装到用户目录而非项目	--global
-a, --agent	指定目标 Agent	-a claude-code cursor
-s, --skill	指定安装的技能名	--skill web-design
-l, --list	仅列出技能，不安装	--list
--copy	复制文件而非创建软链接	--copy
-y, --yes	跳过所有确认提示	-y
--all	安装所有技能到所有 Agent	--all

---

🔹 查看已安装技能：skills list

# 列出所有已安装技能（项目 + 全局）
npx skills list

# 别名：ls
npx skills ls

# 仅查看全局技能
npx skills ls -g

# 按 Agent 筛选
npx skills ls -a claude-code -a cursor

---

🔹 搜索技能：skills find

# 交互式搜索（fzf 风格，支持键盘选择）
npx skills find

# 关键词搜索
npx skills find typescript
npx skills find "pr review"

💡 搜索时会优先展示 skills.sh 排行榜上的高质量技能，避免安装低质量内容。

---

🔹 检查与更新：skills check / skills update

# 检查是否有技能可更新
npx skills check

# 一键更新所有技能到最新版
npx skills update

---

🔹 移除技能：skills remove

# 交互式移除（从列表中选择）
npx skills remove

# 移除指定技能
npx skills remove web-design-guidelines

# 移除多个技能
npx skills remove frontend-design web-design-guidelines

# 从全局作用域移除
npx skills remove --global web-design-guidelines

# 仅从特定 Agent 移除
npx skills remove --agent claude-code cursor my-skill

# 批量移除（无确认）
npx skills remove --all

# 移除某 Agent 的所有技能
npx skills remove --skill '*' -a cursor

# 从所有 Agent 移除指定技能
npx skills remove my-skill --agent '*'

# 别名：rm
npx skills rm my-skill

📋 remove 命令选项

选项	说明
-g, --global	从全局目录移除
-a, --agent	指定 Agent（'*' 表示全部）
-s, --skill	指定技能名（'*' 表示全部）
-y, --yes	跳过确认
--all	shorthand for --skill '*' --agent '*' -y

---

🔹 创建新技能：skills init

# 在当前目录创建 SKILL.md 模板
npx skills init

# 在子目录创建新技能
npx skills init my-skill

生成的模板结构：

---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Instructions for the agent to follow when this skill is activated.

## When to Use

Describe the scenarios where this skill should be used.

## Steps

1. First, do this
2. Then, do that

---

🤖 支持的 AI Agent（40+）

Skills CLI 自动检测已安装的 Agent，也支持手动指定：

Agent	--agent 参数	项目路径	全局路径
Claude Code	claude-code	.claude/skills/	~/.claude/skills/
Cursor	cursor	.agents/skills/	~/.cursor/skills/
Codex	codex	.agents/skills/	~/.codex/skills/
OpenCode	opencode	.agents/skills/	~/.config/opencode/skills/
GitHub Copilot	github-copilot	.agents/skills/	~/.copilot/skills/
Cline / Warp	cline, warp	.agents/skills/	~/.agents/skills/
Gemini CLI	gemini-cli	.agents/skills/	~/.gemini/skills/
…	更多见项目文档

⚠️ Kiro CLI 用户注意：安装后需手动在 .kiro/agents/<agent>.json 中添加：

{
  "resources": ["skill://.kiro/skills/**/SKILL.md"]
}

---

🧩 什么是 Agent Skills？

Agent Skills 是定义在 SKILL.md 文件中的可复用指令集，通过 YAML frontmatter 声明：

---
name: pr-review-helper
description: 自动审查 PR 并给出改进建议
allowed-tools: ["git", "gh"]
---

技能能做什么？

• 📝 自动生成 Release Notes
• 🔍 按团队规范创建 PR
• 🔗 集成外部工具（Linear、Notion、Jira 等）
• 🧪 生成测试用例
• 🎨 遵循设计规范生成 UI 代码

技能文件结构

my-skill/
├── SKILL.md          # 核心定义文件（必需）
├── README.md         # 可选：技能说明
├── examples/         # 可选：使用示例
└── scripts/          # 可选：辅助脚本

高级配置选项

---
name: advanced-skill
description: 支持高级特性的技能
metadata:
  internal: true      # 标记为内部技能，默认不显示
  version: 1.2.0
  author: your-name
allowed-tools:        # 声明技能需要的工具权限
  - git
  - gh
  - npm
context: fork         # Claude Code 特有：在 fork 上下文中运行
hooks:                # Claude Code / Cline 特有：生命周期钩子
  on-load: ./scripts/init.sh
---

---

🔍 技能发现机制

CLI 会在以下位置自动搜索 SKILL.md：

✅ 根目录（如果包含 SKILL.md）
✅ skills/
✅ skills/.curated/、.experimental/、.system/
✅ 各 Agent 专用目录：.claude/skills/、.cursor/skills/ 等
✅ 递归搜索整个仓库（作为 fallback）

插件市场兼容

如果存在 .claude-plugin/marketplace.json，技能也会被自动发现：

{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [{
    "name": "my-plugin",
    "source": "my-plugin",
    "skills": ["./skills/review", "./skills/test"]
  }]
}

---

⚙️ 实用技巧与最佳实践

1️⃣ 项目级 vs 全局安装

# 项目级（默认）：技能随项目提交，团队共享
npx skills add my-org/project-skills

# 全局：个人常用技能，跨项目生效
npx skills add personal/utils --global

2️⃣ 软链接 vs 复制

方式	优点	适用场景
Symlink（默认）	单源维护，更新方便	大多数情况 ✅
Copy	兼容不支持软链接的环境	Windows 特殊场景

# 强制使用复制模式
npx skills add repo --copy

3️⃣ CI/CD 自动化集成

# .github/workflows/install-skills.yml
name: Install Agent Skills
on: [push]
jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install skills for Claude Code
        run: npx skills add vercel-labs/agent-skills --skill ci-helper -g -a claude-code -y

4️⃣ 环境变量控制

# 显示并安装内部技能
INSTALL_INTERNAL_SKILLS=1 npx skills add repo --list

# 禁用遥测（隐私保护）
DISABLE_TELEMETRY=1 npx skills add ...
# 或
DO_NOT_TRACK=1 npx skills add ...

---

🐛 常见问题排查

❌ “No skills found”

# 检查点：
# 1. 仓库是否包含有效的 SKILL.md？
# 2. frontmatter 是否包含 name 和 description？
# 3. 文件编码是否为 UTF-8？

# 调试命令
npx skills add repo --list  # 预览可安装技能

❌ 技能安装后 Agent 不识别

# 排查步骤：
# 1. 确认安装路径是否正确
ls -la .claude/skills/  # Claude Code 示例

# 2. 检查 SKILL.md YAML 语法
# 可使用 yamllint 验证

# 3. 重启 Agent 或重载配置

❌ 权限错误

# 确保对目标目录有写权限
# 全局安装可能需要 sudo（不推荐），建议修改目录权限：
sudo chown -R $USER ~/.claude/skills

---

🌟 实战示例：为团队配置前端开发技能

# 1. 安装官方前端技能包
npx skills add vercel-labs/agent-skills \
  --skill frontend-design \
  --skill react-best-practices \
  --skill tailwind-helper \
  -a claude-code cursor \
  -y

# 2. 创建团队自定义技能
npx skills init team-coding-standards

# 3. 编辑 SKILL.md 添加团队规范
# ...（填写具体规则）

# 4. 提交到项目仓库，团队成员一键同步
git add .agents/skills/team-coding-standards
git commit -m "chore: add team coding standards skill"

---

🔗 资源汇总

• 📚 官方文档：GitHub - vercel-labs/skills
• 🛒 技能市场：skills.sh
• 📐 技能规范：Agent Skills Specification
• 💬 社区讨论：GitHub Discussions

---

🎯 结语

vercel-labs/skills 不仅仅是一个 CLI 工具，更是 AI 编程时代的「能力插件系统」。通过标准化的技能定义，你可以：

✅ 复用：一次编写，多 Agent 通用
✅ 协作：团队技能包随项目共享
✅ 进化：社区生态持续丰富能力边界

💡 给开发者的建议：从安装一个官方技能开始体验，再尝试创建自己的第一个 SKILL.md。当你发现某个操作流程需要反复向 AI 描述时，就是把它封装成技能的最佳时机。

---

📌 本文基于 vercel-labs/skills v1.4.6 编写，命令可能随版本更新略有变化，建议使用时查阅最新文档。

🔖 标签：#AI #DeveloperTools #CLI #Vercel #AgentSkills