Agent Skills CLI（Vercel）

vercel-labs/skills 的 CLI 工具说明，包括工具定位、核心命令、安装管理、工作原理与生态工具链。

#type / resource #status / evergreen #tech / ai #resource / agent-skills-cli #platform / cli

[!info] related notes

Agent Skills CLI（Vercel）

一句话定义

vercel-labs/skills 是开放 Agent Skills 生态的包管理器，不是”技能包仓库”，核心命令是 npx skills ...。类似 npm 之于 JavaScript 包，它解决的是”怎么发现、安装、使用、更新和管理 Agent Skills”的问题。

官方 README 的描述是：“The CLI for the open agent skills ecosystem”，并支持 Codex、Claude Code、Cursor、OpenCode、Gemini CLI、GitHub Copilot 等多种 agent。

核心概念快速回顾

什么是 Agent Skill

Agent Skill 是一个可复用的工作说明书目录，包含：

  • SKILL.md：核心说明与触发条件（name、description、instructions）
  • scripts/：可执行脚本（Python、Bash 等）
  • references/：参考文档（模板、规则、API 说明等）
  • assets/：输出素材（模板文件、样式、示例代码等）

Skill 与普通 Prompt 的区别

方面普通 PromptSkill
形态临时文本结构化目录 + 文件
触发手动粘贴每次元数据自动触发
扩展只有文字支持脚本、文档、资源
复用团队内传播可打包、版本控制、跨 agent
加载一次全部渐进式（metadata → SKILL.md → resources）

CLI 工具的核心职责

三层工作流

第一层：发现 Skill

  • CLI 搜索标准位置：.agents/skills/、.claude/skills/、.codex/skills/、skills/ 等
  • 读取每个目录中的 SKILL.md

第二层：解析元数据

  • 提取 name 和 description（决定何时触发）
  • 为 agent 在决策时提供选项

第三层：安装到 Agent

  • 将 skill 放到目标 agent 能识别的路径
  • 支持 symlink（推荐）或 copy 两种方式
  • 记录已安装 skill 的清单

安装范围的二分法

项目级安装（默认）

  • 位置：.agents/skills/
  • 适用：团队内共享、项目专用 skill

全局安装（加 -g 标志）

  • Codex：~/.codex/skills/
  • Claude Code：~/.claude/skills/
  • Cursor：~/.cursor/skills/
  • 其他 agent 有各自的全局路径
  • 适用：所有项目都用的通用 skill

核心命令速查

1. 查找 Skill

# 搜索已发布的 skill（来自 skills.sh）
npx skills find nextjs
npx skills find "react performance"

2. 安装 Skill

# 从 GitHub 安装整个仓库的所有 skills
npx skills add vercel-labs/agent-skills

# 从 GitHub 安装单个 skill
npx skills add vercel-labs/agent-skills --skill frontend-design

# 从 GitLab、Git URL、本地路径等安装
npx skills add https://github.com/user/my-skills.git
npx skills add ./local/path/to/skills

# 全局安装到用户目录
npx skills add vercel-labs/agent-skills -g

# 指定 agent 类型（可选）
npx skills add vercel-labs/agent-skills -a codex

3. 查看已安装 Skill

# 列出所有已安装 skill
npx skills list
npx skills ls

4. 使用（不安装）

# 临时生成 skill 的 prompt（不持久化）
npx skills use vercel-labs/agent-skills

# 用特定 agent 打开 skill
npx skills use vercel-labs/agent-skills --agent codex

5. 更新 Skill

# 更新所有已安装 skill
npx skills update

# 更新特定 skill
npx skills update my-skill

6. 移除 Skill

npx skills remove my-skill

7. 创建新 Skill

# 生成新 skill 的 SKILL.md 模板
npx skills init my-skill

数据来源格式

CLI 支持多种 source 指定方式：

格式例子
GitHub 简写vercel-labs/agent-skills
完整 GitHub URLhttps://github.com/vercel-labs/agent-skills.git
GitLab URLhttps://gitlab.com/user/skills.git
任意 Git URLhttps://git.example.com/repo.git
本地路径./local/my-skills
单个 skill 目录vercel-labs/agent-skills/skills/frontend

渐进式加载机制

这是 Agent Skills 设计的核心，解决了”skill 多了会爆上下文”的问题。

加载阶段

阶段 1：元数据

  • 时机：Agent 初始化时
  • 内容：name + description
  • 作用：Agent 判断”有这个能力吗？这个任务匹配吗？”

阶段 2：SKILL.md 正文

  • 时机：用户任务匹配这个 skill 时
  • 内容：完整的 instructions
  • 作用：告诉 agent 这个 skill 怎么做事

阶段 3：支持资源

  • 时机：skill 执行过程中需要时
  • 内容：references/、scripts/、assets/
  • 作用：按需加载背景知识、执行脚本、获取模板

为什么这样设计

  • 不浪费上下文：大量 skill 不会一开始全进入上下文窗口
  • 快速决策：Agent 只需看名字和描述就能判断是否相关
  • 按需详化：复杂资源只在真正用到时才读取

Vercel 官方生态补充

vercel-labs/skills（本仓库）

  • 角色：CLI 工具本体 + 一个辅助 skill（find-skills）
  • what：npx skills 命令的实现，包括 add/list/find/update 等功能
  • skills 目录：主要包含 find-skills/SKILL.md，用来帮助 agent 发现和推荐第三方 skill

vercel-labs/agent-skills

  • 角色：Vercel 官方维护的 skill 集合
  • what：一组真正可安装的技能（类似 npm 包）
  • 涵盖范围：Next.js、数据分析、设计规范、工程流程等

skills.sh

  • 角色：Skill 发现排行榜、搜索站点
  • what：类似 npm.js.org，展示已发布 skill 的安装量、GitHub star、描述信息
  • 用途：npx skills find 的数据源

实践用法举例

场景 1：为团队项目添加编码标准

# 安装公司内部的编码 skill
npx skills add our-org/code-standards

# 检查是否安装成功
npx skills list

# 从此以后，agent 在编码时自动遵循这套规范

场景 2：尝试第三方 skill（不安装）

# 临时查看某个 skill 的完整内容
npx skills use vercel-labs/agent-skills --skill qa-testing

# 如果觉得有用，再正式安装
npx skills add vercel-labs/agent-skills --skill qa-testing

场景 3：发现新 skill

# 搜索与 Next.js 相关的 skill
npx skills find next.js

# CLI 会列出 skills.sh 上的推荐 skill（包括安装量、来源等）
# 用户可以选择安装哪一个

场景 4：创建团队自己的 skill

# 在仓库中初始化一个新 skill
npx skills init pr-review-checklist

# 编辑生成的 SKILL.md
# 添加 references/、scripts/ 等支持文件

# 然后在团队内安装
npx skills add ./pr-review-checklist

核心特性与价值

1. 跨 Agent 复用

同一套 skill 可以被多个 agent 使用：

  • Codex
  • Claude Code
  • Cursor
  • OpenCode
  • Gemini CLI
  • GitHub Copilot

这意味着不用为每个 agent 重复编写同样的规范和流程。

2. 版本控制与演进

  • Skill 作为 Git 仓库的一部分，可以追踪历史
  • 团队可以共同维护 skill，CI/CD 可以自动化更新
  • npx skills update 拉取最新版本

3. 渐进式披露降低认知负担

  • Agent 不会被海量 skill 淹没
  • 只在相关时刻才读完整内容
  • 上下文使用更高效

4. 打包边界清晰

  • Skill 不只是文字，还能包含脚本、资源
  • 指定性强：不需要再说”某个步骤按照这个文档做”
  • 可维护性强：更新一个地方，所有使用者同步受益

什么时候值得投入 Skill

适合的场景

  • 团队反复让 agent 做同一类任务
  • 任务有稳定的流程和约束规则
  • 需要在 Codex、Claude Code 等多个 agent 间复用
  • 想把隐性经验（经验法则、企业规范）变成可维护资产
  • 任务涉及复杂的多步脚本或特定格式输出

不太适合的场景

  • 流程本身还在频繁变化（容易把混乱固化）
  • 只是临时的一次性指令
  • 仅涉及单个简单工具的调用（那用 MCP tool 或 function calling 可能更轻）

与其他概念的区别

概念定位与 Skill 的关系
Prompt临时对话指令Skill 内包含 prompt-like instructions
MCP Tools单个能力接口Skill 比 tool 重，可以组合多个 tool
Function Calling模型调用函数Skill 可以指导何时、如何调用 function
Workflow自动化编排Skill 是可被 workflow 触发的基础单元

质量与安全考量

搜索与推荐的建议

vercel-labs/skills 仓库中的 find-skills skill 明确强调：

  • 不要只凭搜索结果推荐 skill，要看安装量、来源声誉、GitHub star等质量信号
  • 优先选择由知名组织或多人维护的 skill
  • 新手 skill 可以试用，但用在生产流程前要审查内容

权限与上下文安全

  • Skill 本身是文件和指令，不自动带来外部权限
  • 包含脚本的 skill 需要审查（可能执行任意代码）
  • 建议在项目级别先试用，验证后再全局安装

相关资源

总结

Agent Skills CLI 的真正意义在于：

  • 把临时 prompt 工程化成可管理生态
  • 让团队知识和规范从聊天记录沉淀为版本化资产
  • 支持渐进式加载，不会因 skill 多就爆炸上下文
  • 跨 agent 复用，避免重复编写同样的规范

如果你的团队有稳定的编码规范、工程流程或领域知识，Skill 是一个低开销、高收益的投资。

创建于 2026/6/5 更新于 2026/6/5