lightweight-charts

敏而好学，不耻下问。——孔子

Skills：让 AI 编程代理拥有一套可安装、可共享、可更新的技能系统

项目地址：https://github.com/vercel-labs/skills

AI 编程代理越来越像开发流程中的正式参与者。

它们可以阅读代码、修改文件、执行命令、编写测试、整理提交记录，也可以围绕项目规范完成特定任务。但代理本身并不会天然理解每个团队的代码习惯、发布规则、设计规范、工具接入方式与协作流程。

于是，一个问题慢慢浮现出来：

能不能像管理依赖一样，管理代理的工作技能？

Skills 给出的答案是可以。

它是开放 Agent Skills 生态的命令行工具，提供了一套围绕 SKILL.md 的安装、发现、使用、更新、删除与创建机制。通过一条 npx skills 命令，开发者可以把可复用的指令集安装到不同 AI 编程代理中，也可以在不安装的情况下临时调用某项技能。

它支持 OpenCode、Claude Code、Codex、Cursor，以及更多代理环境。

Skills 做的事情并不复杂，却很有代表性：把原本散落在提示词、团队文档、项目说明和个人经验中的工作方式，整理为一种可分发、可复用、可维护的技能单元。

Agent Skill 是什么

Agent Skill 可以理解为一套可复用的代理指令。

它通过一个名为 SKILL.md 的文件定义，文件顶部包含 YAML frontmatter，其中至少需要有两个字段：

• name
• description

一个最基础的 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

其中，name 是技能的唯一标识符，使用小写字母，并允许使用连字符。

description 用于说明技能做什么，以及应该在什么情形下使用。

而正文部分则承载真正交给代理的指令：什么时候启用、要遵循哪些步骤、应当注意哪些约束、如何完成对应任务。

一项 Skill 可以是代码评审规则。

可以是发布说明生成流程。

可以是某个前端设计规范。

可以是团队创建 Pull Request 时必须遵循的步骤。

也可以是连接 Linear、Notion 等外部工具的工作说明。

Skills 的作用，就是让这些指令不必每次靠人重新输入，也不必只停留在某份难以发现的文档中。

一条命令，把技能交给代理

安装一个 Skill 的最简单方式如下：

npx skills add vercel-labs/agent-skills

这条命令会从指定来源发现可用技能，并将它们安装到本地可识别的代理目录中。

Skills 会自动检测当前机器上已经安装的编码代理。如果没有检测到可用代理，工具会提示用户选择要安装到哪些代理。

这让同一份技能不必只绑定某一种工具。

团队可以使用 Claude Code。

个人可以使用 Codex。

项目中的其他成员也许习惯 Cursor、OpenCode、GitHub Copilot 或其他代理环境。

Skills 尝试在这些不同环境之间提供统一的技能安装入口。

不安装，也可以临时使用一项 Skill

并不是每一项技能都需要长期写入项目或全局目录。

有时候，只是想针对一次任务使用某条规则，或者先试试看一项技能会生成怎样的提示内容。Skills 为这种情形提供了 use 命令。

npx skills use vercel-labs/agent-skills@web-design-guidelines | claude

也可以明确指定目标代理：

npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code

skills use 会按照与 skills add 相同的方式解析来源，将选定 Skill 写入临时目录，并默认只把生成后的提示内容输出到标准输出。

如果提供 --agent 参数，它则可以交互式启动受支持的编码代理。

这种模式很适合临时任务。

比如想让代理按照某项网页设计规范执行一次工作，但又不希望把这项规范永久安装进项目目录。又或者，团队正在评估一套新的技能规则，希望先在实际任务中体验它的效果。

技能不必非得成为长期配置，才能发挥作用。

来源不只来自 GitHub 仓库

Skills 支持多种来源形式。

最常见的是 GitHub 简写：

npx skills add vercel-labs/agent-skills

也可以使用完整的 GitHub 地址：

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、Azure Repos、普通 Git 地址与本地目录。

npx skills add https://gitlab.com/org/repo

npx skills add https://dev.azure.com/org/project/_git/repo

npx skills add git@github.com:vercel-labs/agent-skills.git

npx skills add ./my-local-skills

这让 Skill 的来源不被限制在某个单一代码托管平台。

团队可以维护内部 Git 仓库。

个人可以在本地目录中开发一组技能。

组织也可以在已有代码库中维护与项目一起演进的代理规范。

Skill 的分发方式，能够贴合不同团队原本就存在的代码管理方式。

私有仓库里的团队规范，也可以成为技能

很多有价值的技能并不会公开。

团队内部的发布流程、架构约束、安全要求、代码审查标准、产品术语和工具接入规则，往往都保存在私有仓库中。

Skills 对公共仓库与私有仓库使用同一条安装命令。

npx skills add acme/private-skills

也可以使用 SSH 来源：

npx skills add git@github.com:acme/private-skills.git

npx skills add ssh://git@git.example.com/acme/private-skills.git

还可以通过 HTTPS 使用已经配置好的 Git 凭据：

npx skills add https://git.example.com/acme/private-skills.git

对于 GitHub 简写和 HTTPS 来源，Skills 会优先使用正常 Git 凭据。如果失败，并且 GitHub CLI 已经完成认证，它会尝试使用 GitHub CLI，再尝试 SSH。

对于 GitHub 中的目录定位，它会依次尝试匿名 API、显式环境令牌与 GitHub CLI API。

可选的 GITHUB_TOKEN 与 GH_TOKEN 环境变量可用于经过认证的 GitHub API 请求，包括私有仓库下载与更新检查。

这种处理方式让私有技能不必脱离原有的权限体系。

团队不必为了分发代理技能额外建立一套全新账户机制。已有的 Git、SSH、GitHub CLI 与凭据助手，可以继续承担访问控制职责。

项目级安装与全局安装

一项 Skill 应该跟随项目，还是跟随个人开发环境？

Skills 为这两种需求提供了不同范围。

默认情况下，Skill 安装到项目范围。

./<agent>/skills/

这种方式适合希望将代理规范和项目一起提交、一起共享的团队。

项目中的每位成员拿到同一份代码时，也能拿到同一套 Skill 配置。

如果使用 -g 或 --global，Skill 则安装到用户目录。

~/<agent>/skills/

这种方式适合个人长期使用的通用技能。

例如，个人习惯的代码审查流程、常用的文档生成方式、特定技术栈中的最佳实践，都可以作为全局技能跨项目复用。

项目级技能更像项目的一部分。

全局技能更像个人开发环境的一部分。

两种范围并不互相排斥，而是对应不同层次的工作习惯。

符号链接与复制，两种安装方式

当一个 Skill 需要安装到多个代理时，如何避免维护多份重复文件，也是一个现实问题。

Skills 在交互式安装中提供两种方式。

第一种是符号链接。

第二种是复制。

符号链接是推荐方式。它会在不同代理目录中创建指向规范副本的链接，从而保持单一事实来源，并且便于更新。

复制则会为每个代理创建独立副本，适用于不支持符号链接的环境。

这两种方式分别对应不同的维护策略。

符号链接强调统一与更新便利。

复制强调独立与兼容。

对于需要在多个代理中使用同一套规则的人来说，这一层选择并不是细节，而是决定未来维护成本的结构性问题。

精确选择要安装的技能和代理

Skills 支持只安装指定名称的 Skill。

npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator

如果 Skill 名称中含有空格，需要使用引号：

npx skills add owner/repo --skill "Convex Best Practices"

也可以明确选择安装目标代理：

npx skills add vercel-labs/agent-skills -a claude-code -a opencode

对于持续集成或非交互式环境，可以跳过确认步骤：

npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y

如果想安装仓库中的全部技能到所有代理：

npx skills add vercel-labs/agent-skills --all

如果只想把全部技能安装给某一个代理：

npx skills add vercel-labs/agent-skills --skill '*' -a claude-code

如果只想把一个具体技能安装到所有代理：

npx skills add vercel-labs/agent-skills --agent '*' --skill frontend-design

这种组合能力让 Skills 不只是一个“一键安装器”。

它也可以精确地管理技能与代理之间的关系。

同一份技能库中，某些规则适用于 Claude Code，另一些只适用于 Codex，某些又应该提供给全部代理。安装时的选择能力，让团队可以把这些差异明确表达出来。

技能的完整生命周期

安装只是开始。

当团队规则更新，技能需要跟进。

当项目不再需要某项规范，技能应当能够被移除。

当开发者想知道当前环境中究竟安装了哪些技能，也需要有清晰的查看方式。

Skills 为此提供了一组生命周期命令。

npx skills use <source>
npx skills list
npx skills find [query]
npx skills remove [skills]
npx skills update [skills]
npx skills init [name]

其中，skills list 用于查看已安装技能。

npx skills list

只查看全局技能：

npx skills ls -g

按代理过滤：

npx skills ls -a claude-code -a cursor

skills update 用于更新技能。

npx skills update

更新单个技能：

npx skills update my-skill

更新多个指定技能：

npx skills update frontend-design web-design-guidelines

只更新全局范围：

npx skills update -g

只更新项目范围：

npx skills update -p

非交互式更新：

npx skills update -y

skills remove 则用于移除技能。

npx skills remove

移除特定技能：

npx skills remove web-design-guidelines

从指定代理中移除：

npx skills remove --agent claude-code cursor my-skill

移除全部已安装技能：

npx skills remove --all

Skill 不再只是一次性复制到某个目录的 Markdown 文件，而拥有了安装、查看、更新、删除与初始化的完整管理流程。

skills find：从搜索开始发现技能

当技能数量增长，知道“自己需要什么”并不总是容易。

Skills 提供 find 命令，用于交互式或按关键字搜索技能。

npx skills find

这会进入类似 fzf 风格的交互式搜索体验。

也可以直接按关键词查找：

npx skills find typescript

如果希望搜索某个组织或用户拥有的全部仓库，可以指定拥有者：

npx skills find react --owner vercel

这让技能发现不再完全依赖记住某个仓库名称。

当技能逐渐成为一种可共享的开发资源时，搜索本身也会成为生态中的重要入口。

skills init：从模板开始创建自己的 Skill

除了使用别人提供的技能，Skills 也支持创建新的 Skill 模板。

在当前目录创建：

npx skills init

在子目录中创建：

npx skills init my-skill

这一步很轻，却让技能的生产与消费形成了闭环。

团队可以从一个模板开始，把已有的工作习惯整理出来。

例如：

• 生成变更日志的规则
• 创建 Pull Request 的流程
• 处理某类线上问题的检查清单
• 使用某套组件库的设计规范
• 提交数据库迁移前的验证步骤
• 生成 API 文档时必须遵循的格式
• 接入某个外部平台时的约束和命令

当这些信息被写进 SKILL.md，它们不再只是靠口口相传维持的经验，也不只是藏在某个聊天记录或内部 Wiki 中的长文。

它们可以被代理发现、加载和执行。

技能发现并不只搜索一个固定目录

不同代理生态有不同的 Skill 目录约定。

Skills 面对的是大量不同工具，因此它需要识别多种目录结构。

它会在仓库中搜索根目录的 SKILL.md，也会搜索 skills/、.claude/skills/、.agents/skills/、.cursor 相关目录、.kiro/skills/、.qwen/skills/、.windsurf/skills/ 等多个位置。

对于 Skill 容器目录，Skills 默认会向下查找最多三层。

这覆盖了多种常见布局：

skills/<name>/SKILL.md

skills/<category>/<name>/SKILL.md

skills/<category>/<category>/<name>/SKILL.md

如果较浅层目录已经发现 SKILL.md，它会遮蔽更深层的同名发现结果。

如果需要查找标准容器目录之外的 SKILL.md，例如位于 examples/ 或 tests/ 中的文件，可以使用 --full-depth。

如果标准路径中没有发现任何技能，Skills 还会进行递归搜索。

这种发现策略的意义在于，Skill 不必为了被工具识别而被迫采用单一仓库结构。

团队可以维护平铺式技能目录。

也可以按照领域分类。

还可以把技能嵌入不同代理工具本身已有的目录约定中。

Claude 插件清单中的技能，也能被发现

Skills 还支持从 Claude 插件清单中发现技能。

如果仓库中存在：

.claude-plugin/marketplace.json

或者：

.claude-plugin/plugin.json

工具会读取其中声明的 Skill 路径。

例如：

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

这种能力让 Skills 能够兼容 Claude Code 插件市场生态中的技能声明方式。

对开发者而言，技能不需要因为换了分发机制就失去可发现性。无论是独立仓库目录，还是插件清单中声明的路径，Skills 都能够尝试将它们纳入统一发现流程。

支持的代理，不只是几个熟悉的名字

Skills 支持的代理范围很广。

其中包括 Claude Code、Codex、Cursor、OpenCode、GitHub Copilot、Gemini CLI、OpenClaw、Kiro CLI、Qwen Code、Windsurf、Zed、Cline、Roo Code、Continue、OpenHands、Kimi Code CLI、Antigravity、Amp、Replit、Droid、Goose、Augment、CodeBuddy、MCPJam、Pi、Warp 等环境。

不同代理使用不同的项目路径与全局路径。

例如，Claude Code 的项目路径为：

.claude/skills/

全局路径为：

~/.claude/skills/

Codex 的项目路径为：

.agents/skills/

全局路径为：

~/.codex/skills/

Cursor 的项目路径为：

.agents/skills/

全局路径为：

~/.cursor/skills/

GitHub Copilot 的项目路径为：

.agents/skills/

全局路径为：

~/.copilot/skills/

OpenCode 的项目路径为：

.agents/skills/

全局路径为：

~/.config/opencode/skills/

这种差异正是 Skills 需要存在的原因之一。

如果每一种代理都要求用户手工记住各自的目录规则，那么共享一份 Skill 往往会变成一件重复而容易出错的事情。

Skills 试图把这些路径差异藏在工具背后，让用户更多关注“安装什么技能给哪些代理”，而不是反复处理目录细节。

兼容并不意味着所有高级功能都完全相同

虽然 Agent Skills 遵循共享的规范，并且一般能够跨代理使用，但不同代理对某些能力的支持程度并不相同。

基础 Skill 在多个受支持代理中可以使用。

但 allowed-tools、context: fork 和 Hooks 等特性，可能是特定代理才支持的能力。

例如，README 的兼容性矩阵中显示，Claude Code 支持 context: fork。

而 Hooks 在 Claude Code、Cline 与 Kiro CLI 等部分环境中可用，但并非所有代理都支持。

这并不是缺点，而是跨平台技能系统面对现实差异时的诚实表达。

共享规范可以提供共同基础。

但某些代理拥有更丰富的上下文管理、工具权限或生命周期能力时，技能也可以针对这些能力进行扩展。

内部技能与公开技能

并不是每一项 Skill 都应该被普通用户发现和安装。

有些技能可能仍在开发中。

有些只服务于内部工具。

有些可能只适用于特定团队流程。

Skills 支持使用 metadata.internal 标记内部技能。

---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
  internal: true
---

被标记为内部的技能默认不会出现在常规发现结果中。

只有设置环境变量后，才会显示并允许安装：

INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list

这种机制让同一个仓库可以同时承载公开技能与内部技能，而不必让尚未准备好的内容进入默认可见范围。

遥测与隐私控制

Skills 会收集匿名使用数据，用于改进工具。

README 明确说明，该工具不收集个人信息。

对于 GitHub 仓库和 Skill 标识，只有在 GitHub 明确确认仓库为公开仓库时，才会发送这些标识。其他远程来源类型可能在安装遥测中包含来源与技能标识。

如果不希望启用匿名遥测，可以设置：

DISABLE_TELEMETRY=1

也可以设置：

DO_NOT_TRACK=1

对于工具生态来说，匿名使用数据能够帮助维护者理解功能使用情况，而显式关闭选项则让使用者保留选择空间。

从提示词复制，到技能化协作

很多团队已经拥有大量“隐形技能”。

它们可能存在于资深开发者的经验里。

存在于代码评审留言中。

存在于入职文档里。

存在于一段被不断复制粘贴的提示词中。

存在于某份只有少数人知道位置的项目说明里。

Skills 想做的，是让这些知识获得更合适的载体。

一项好的 Skill 不只是告诉代理“做什么”。

它还可以告诉代理“什么时候做”“按什么步骤做”“遵守哪些边界”“输出什么结果”。

于是，代理不再每次都从零理解团队习惯。

团队也不必每次都把同样的规则重复写进对话。

Skill 可以跟随项目提交。

可以全局安装。

可以从公共仓库获取。

可以从私有仓库分发。

可以临时调用。

可以搜索发现。

可以更新和移除。

也可以由团队自己创建。

让代理能力从临时对话，变成可维护资产

AI 编程代理的能力很大一部分来自上下文。

而团队真正有价值的上下文，往往不是一次性提示词，而是长期沉淀下来的规范、流程、经验和约束。

Skills 将这些内容包装为 SKILL.md，再用 CLI 提供安装、发现、更新和跨代理分发能力。

这使得代理技能不再只是一次任务结束后就消失的临时说明。

它们可以成为项目资产。

成为团队协作的一部分。

成为个人开发环境中可以持续维护的能力层。

当越来越多开发工作由人和代理共同完成时，真正重要的不只是代理能不能写代码。

还包括团队能否把自己的工作方式，稳定、清晰、可复用地交给代理。