zhaoweiguo 的知识库

vercel-labs/skills (npx skills CLI)

6分钟阅读

由 Vercel Labs 维护的 AI Agent Skill 包管理器，类比 npm 之于 Node.js 包。通过统一 CLI 从 GitHub 仓库安装、更新、管理各类 Agent Skill，支持 Claude Code、Cursor、Codex、Copilot、Gemini CLI、Kiro 等 40+ harness。当前版本：v1.5.9。

安装与调用

无需全局安装，直接用 npx 调用：

npx skills <command> [options]
# 或全局安装后直接用 skills
npm install -g skills
skills <command>

核心命令

add — 安装 Skill

skills add <package>
# package 格式：owner/repo 或完整 GitHub URL

常用选项：

选项说明
-g, --global全局安装（用户级，~/.agents/skills/），不加则为项目级
-a, --agent <agents>指定目标 agent（claude-code、cursor 等），* 为全部
-s, --skill <skills>只安装包中的指定 skill，* 为全部
-l, --list列出可安装的 skill，不实际安装
-y, --yes跳过确认提示
--copy复制文件而非创建 symlink
--all--skill '*' --agent '*' -y 的简写
--full-depth根目录有 SKILL.md 时仍扫描全部子目录

示例：

# 从 vercel-labs/agent-skills 全局安装全部 skill
skills add vercel-labs/agent-skills -g
 
# 只安装到 Claude Code 和 Cursor
skills add vercel-labs/agent-skills --agent claude-code cursor
 
# 只安装指定的两个 skill
skills add vercel-labs/agent-skills --skill pr-review commit
 
# 先列出可安装内容，再决定是否安装
skills add vercel-labs/agent-skills --list
 
# 安装 monorepo 中单个 skill（--skill flag）
skills add jdevalk/skills --skill astro-seo

remove — 卸载 Skill

skills remove [skills...]
skills rm [skills...]        # 别名
选项说明
-g, --global从全局作用域移除
-a, --agent <agents>只从指定 agent 移除
-s, --skill <skills>指定要移除的 skill 名
-y, --yes跳过确认
--all移除全部（--skill '*' --agent '*' -y）
skills remove web-design            # 按名字移除
skills rm --global frontend-design  # 全局移除
skills remove                       # 交互式选择

list / ls — 列出已安装 Skill

skills list          # 项目级（默认）
skills ls -g         # 全局
skills ls -a claude-code   # 过滤特定 agent
skills ls --json     # JSON 输出（机器可读，无 ANSI 颜色）

find — 搜索 Skill

skills find               # 交互式搜索（浏览 skills.sh 目录）
skills find typescript    # 按关键词搜索

update / upgrade — 更新 Skill

skills update                  # 更新全部（提示选作用域）
skills update my-skill         # 更新单个
skills update -g               # 只更新全局
skills update -p               # 只更新项目级
skills update -g -y            # 全局更新，跳过确认

自动更新：在 ~/.claude/settings.json 中注册 SessionStart Hook，每次 session 启动时（context 外）自动更新：

{
  "hooks": {
    "SessionStart": [{"type": "command", "command": "npx skills update -g -y 2>/dev/null"}]
  }
}

init — 初始化新 Skill

skills init my-skill    # 创建 my-skill/SKILL.md
skills init             # 在当前目录创建 ./SKILL.md

实验性命令

# 从 skills-lock.json 恢复安装（类比 npm ci）
skills experimental_install
 
# 从 node_modules 同步 skill 到 agent 目录
skills experimental_sync
skills experimental_sync -y    # 跳过确认

安装路径与作用域

作用域路径说明
全局（-g）~/.agents/skills/跨 agent 共享，个人开发者工具
Claude Code 专属~/.claude/skills/仅供 Claude Code 读取
项目级<project-dir>/随项目版本控制，团队共享

默认安装方式为 symlink，指向 npm 缓存中的源文件；--copy 改为复制，断开与源的关联。

不指定 -a/--agent 时的行为

不加 -a 参数时，CLI 会交互式询问安装到哪些 agent，让用户勾选。

加 -g 但不加 -a：安装到 ~/.agents/skills/，被所有支持该路径的 agent 共用（Claude Code、OpenClaw、Qoder、Trae、Warp 等）。文件为真实目录，非 symlink。

加 -a claude-code：只安装到 ~/.claude/skills/，仅 Claude Code 可读。

注意：~/.claude/skills/ 和 ~/.agents/skills/ 是两个独立路径。-g 默认写入 ~/.agents/skills/，若需要只让 Claude Code 使用，应显式加 --agent claude-code。

Skill 包结构（SKILL.md 格式）

每个 skill 是 GitHub 仓库下 skills/<skill-name>/ 目录，核心文件是 SKILL.md：

skills/
└── my-skill/
    ├── SKILL.md          # 必填：元数据 + AI 指令
    ├── scripts/          # 可选：Python/Bash 确定性脚本
    ├── assets/           # 可选：模板、图标、示例
    └── references/       # 可选：补充参考文档

SKILL.md 使用 YAML frontmatter 定义元数据：

---
name: my-skill
version: 1.0.0
description: 一句话描述
metadata:
  requires:
    bins: [some-cli]    # 依赖的外部二进制
---
# Skill 指令内容（注入到 AI system prompt）

支持的 Agent

官方支持 40+ agent harness，包括：Claude Code、Cursor、OpenAI Codex、GitHub Copilot、Gemini CLI、Kiro、Windsurf、OpenCode、Goose、Trae、Warp、Qoder 等。

技能发现页面：https://skills.sh/

起源与生态

  • 时间：Agent Skills 格式由 Anthropic 于 2025 年 10 月随 Claude Code 引入
  • 开放化：Vercel Labs 将其标准化为开放规范，现已被 OpenAI Codex、Microsoft、GitHub Copilot、Cursor 等广泛采用
  • 知名发布者：vercel-labs、Vercel、Nylas、NVIDIA、Remotion、Databricks、Joost de Valk（jdevalk/skills）等

关联页面

关系图谱

反向链接