agent-skills 实战：用 CLI 为 AI coding agents 构建可复用技能库

1. 从"装完就吃灰"说起：agent-skills 到底解决什么问题

如果你最近半年在折腾 AI coding agents，大概率经历过这个循环：兴冲冲装好 Claude Code 或者 Cursor，敲了几个 prompt，觉得"也就那样"，然后默默切回原来的工作流。问题往往不在模型本身，而在于 agent 缺少一套可复用、可组合、可版本管理的技能包——也就是 agent-skills 这个概念要解决的核心痛点。

agent-skills 本质上是一套面向 AI coding agents 的能力封装规范与配套 CLI 工具链。它做的事情，用一句话概括：把"你每次都要重新告诉 agent 怎么做某件事"变成"agent 自己知道该调用哪个技能"。比如你想让 agent 帮你做一次规范的 Git commit、生成一份符合团队规范的 PR 描述、或者按固定模板写单元测试，这些重复性的"操作知识"过去只能靠你在 prompt 里反复粘贴，现在可以沉淀成一个个 skill，通过 skills CLI 统一安装、管理和分发。

这套东西适合谁？三类人最该关注。第一类是重度使用 Claude Code、Cursor 这类工具的开发者，你每天要跟 agent 来回对话几十次，skills 能显著减少重复沟通成本。第二类是团队里的效率负责人，你需要把团队的编码规范、发布流程、代码审查清单固化成 agent 能理解的形式，让新人也能一键复用。第三类是喜欢折腾工具链的独立开发者，skills CLI 的插件化设计给了你很大的自定义空间，可以按自己的习惯搭一套专属技能库。

我自己的使用场景很典型：日常在 Claude Code 里做后端开发，同时用 Cursor 处理前端和文档。过去两个工具之间的"操作习惯"是割裂的，同一个规范要在两边各写一遍 prompt。用了 agent-skills 之后，我把常用的十几个操作抽成 skill，两边共享同一套定义，切换工具时几乎零成本。这篇文章就把我从零搭建这套体系的过程完整拆开，包括选型逻辑、目录结构、CLI 实操、踩过的坑，以及怎么判断一个操作值不值得做成 skill。

2. 核心设计思路：为什么是"技能"而不是"提示词"

2.1 提示词工程的三个死结

在 agent-skills 出现之前，大家管理 agent 行为主要靠三种方式：写在系统提示里、存成 prompt 模板文件、或者干脆每次手打。这三种方式我都深度用过，各有各的难受。

写在系统提示里的问题是耦合太重。你把所有规则塞进一个巨大的 system prompt，agent 每次对话都要加载全部内容，token 消耗大不说，规则之间还会互相干扰。我试过在一个系统提示里同时塞进"代码风格规范"和"Git 提交规范"，结果 agent 在写代码时莫名其妙地开始用 commit message 的格式组织注释。

存成 prompt 模板文件的问题是没有结构化。你有一堆.md文件散落在项目里，靠文件名和记忆去调用，agent 并不知道什么时候该用哪个。更麻烦的是，模板之间无法组合——你没法让"生成测试"这个模板自动带上"项目测试规范"这个模板的内容。

每次手打的问题最直接：不可复用、不可版本管理、团队无法共享。你今天调好的一段 prompt，明天换个项目就得重来，同事想用还得你复制粘贴给他。

2.2 skill 的封装逻辑：把"怎么做"和"做什么"分离

agent-skills 的设计思路，本质上是把操作知识从具体任务里剥离出来。一个 skill 描述的是"做某类事情的标准流程"，而不是"这次具体要做什么"。

打个比方。传统 prompt 像是你每次做饭都要口头指挥厨师："先热锅，倒油，油温七成热下葱姜……"而 skill 像是给厨师一本菜谱，里面写好了"红烧类菜品通用流程"，厨师看到你要做红烧肉，自己就翻到那一页照着做。你只需要说"做个红烧肉"，剩下的流程知识由 skill 提供。

这个分离带来三个直接好处。第一是复用性：同一个"代码审查"skill，可以用在任何语言、任何项目的审查任务上，只要任务描述不同。第二是可组合性：一个 skill 可以引用另一个 skill，比如"发布流程"skill 内部可以调用"版本号更新"和"变更日志生成"两个子 skill。第三是可维护性：规范变了只需要改 skill 定义，所有引用它的地方自动生效，不用去每个 prompt 里改。

2.3 为什么需要 CLI 而不是纯文件

有人会问：既然 skill 就是文件，我手动放到目录里不就行了，为什么要搞个 CLI？

我一开始也是这么想的，手动建目录、手动复制文件，用了两周就受不了了。核心问题在于依赖管理和版本同步。当你有了几十个 skill，它们之间会有依赖关系，有的 skill 依赖特定版本的另一个 skill，手动管理根本管不过来。而且团队协作时，你怎么保证每个人本地的 skill 版本一致？靠口头约定显然不现实。

skills CLI 解决的就是这些工程化问题：安装、卸载、更新、依赖解析、版本锁定，跟包管理器是一个思路。你可以把它理解成"agent 技能界的 npm"。这个类比很准确——skill 就是 package，CLI 就是包管理器，skill 仓库就是 registry。

提示：不要把 skill 想得太重。一个 skill 可以简单到只有几行说明，比如"提交代码前必须运行 lint"。轻量、单一职责的 skill 比大而全的 skill 更好维护，也更容易组合。

3. 环境准备与 skills CLI 安装实操

3.1 前置条件确认

在动手之前，先确认你的环境满足基本要求。我踩过的第一个坑就是环境没对齐，装到一半各种报错。

Node 版本这块特别提醒一句：skills CLI 内部用了较新的 ESM 特性，Node 16 会直接报模块解析错误。如果你机器上有多个 Node 版本，建议用 nvm 切到 18 或 20。我自己用的是 20 LTS，实测最稳。

3.2 安装 skills CLI 的两种方式

方式一：全局安装（推荐给个人开发者）

npm install -g @agent-skills/cli

装完之后验证：

skills --version

能正常输出版本号就说明装好了。全局安装的好处是任何目录下都能直接用skills命令，适合你需要在多个项目间切换的场景。

方式二：项目内安装（推荐给团队协作）

npm install -D @agent-skills/cli

然后在package.json的 scripts 里加一行：

{ "scripts": { "skills": "skills" } }

这样团队成员 clone 项目后npm install就自动装好了 CLI，版本也锁在 lockfile 里，不会出现"你装的是 1.2 我装的是 1.5"这种问题。团队场景强烈建议用这种方式。

3.3 初始化 skill 工作目录

装好 CLI 后，第一步是初始化工作目录。在项目根目录执行：

skills init

这个命令会做三件事：创建.agent-skills/目录、生成skills.config.json配置文件、在当前 agent 的配置目录里建立软链接。

生成的目录结构大概是这样：

.agent-skills/ ├── skills.config.json # 全局配置 ├── registry.json # 已安装 skill 的清单和版本 └── skills/ # skill 实际存放位置 └── .gitkeep

skills.config.json里有几个关键字段需要你确认：

{ "agent": "claude-code", "skillDir": "./.agent-skills/skills", "autoSync": true, "registry": "https://your-registry-url" }

agent字段决定 skill 最终同步到哪个工具的配置目录。如果你同时用 Claude Code 和 Cursor，可以配成数组，CLI 会同时同步到两边。autoSync打开后，每次安装或更新 skill 会自动同步，省得手动跑同步命令。

注意：registry字段如果你用的是团队私有仓库，需要填团队内部的地址。用公开仓库的话保持默认即可。私有仓库的鉴权配置在 CLI 的全局配置里，不在项目配置里，避免把凭证提交到 Git。

4. 第一个 skill：从零写一个可用的技能定义

4.1 skill 文件的基本结构

一个 skill 就是一个 Markdown 文件，加上一段 YAML frontmatter。别被"frontmatter"这个词吓到，就是文件开头用---包起来的一段元数据。

我拿一个最实用的例子来演示：规范化的 Git 提交。这个操作几乎每天都要做，而且格式要求固定，最适合做成 skill。

在.agent-skills/skills/下新建git-commit.md：

--- name: git-commit description: 按团队规范生成并执行 Git 提交 version: 1.0.0 triggers: - 提交代码 - commit - 生成提交信息 dependencies: [] --- # Git 提交规范 当用户要求提交代码时，按以下流程执行： 1. 运行 `git status` 和 `git diff --staged` 查看暂存区变更 2. 如果暂存区为空，提示用户先 `git add` 3. 分析变更内容，判断类型（feat/fix/docs/refactor/test/chore） 4. 生成符合 Conventional Commits 规范的提交信息 5. 提交信息格式：`<type>(<scope>): <subject>` 6. subject 使用中文，不超过 50 字符，不以句号结尾 7. 执行 `git commit -m "<生成的提交信息>"` ## 约束 - 禁止在提交信息里出现"更新""修改"这类无信息量的词 - 一次提交只做一件事，如果变更混杂要提示用户拆分 - 提交前必须确认没有调试代码残留（console.log、debugger 等）

4.2 关键字段逐个拆解

name是 skill 的唯一标识，用小写加连字符，跟 npm 包命名规则一致。这个名字会用在 CLI 命令里，比如skills install git-commit，所以起名要短、要准。

description是给 agent 看的，决定 agent 什么时候会想起调用这个 skill。这里有个经验：description 要写"什么时候用"，而不是"这是什么"。写"按团队规范生成并执行 Git 提交"比写"Git 提交技能"效果好得多，因为前者包含了触发场景。

triggers是显式触发词。当用户的输入里包含这些词时，agent 会优先考虑加载这个 skill。这个字段不是必须的，但加上之后命中率明显提升。我实测下来，中文触发词比英文更管用，因为大家平时说话还是用中文。

dependencies是依赖的其他 skill。比如你的提交 skill 可能依赖一个"代码检查"skill，就可以在这里声明。CLI 安装时会自动把依赖一起装上。

4.3 正文部分的写法要点

frontmatter 下面的正文，就是 skill 的"操作手册"。写法上有几个要点。

用编号步骤，不用大段描述。agent 解析编号列表比解析段落文本准确得多。每一步都要是可执行的动作，而不是抽象的原则。写"运行 git status 查看变更"比写"了解当前代码状态"强太多。

约束单独成节。把禁止事项、边界条件放在## 约束下面。agent 对"禁止""必须""不要"这类词的敏感度很高，单独成节能确保它不会漏掉。

给具体格式示例。涉及格式的地方，直接给一个例子。上面那个<type>(<scope>): <subject>就是格式模板，agent 照着填就行，不用自己猜。

4.4 安装并验证

写好文件后，用 CLI 安装到本地：

skills install ./skills/git-commit.md

或者如果 skill 已经在 registry 里：

skills install git-commit

安装完跑一下验证：

skills list

应该能看到git-commit@1.0.0出现在列表里。然后打开 Claude Code 或 Cursor，随便改点代码，输入"帮我提交代码"，看 agent 是否按规范执行。如果没触发，检查两件事：triggers 里有没有匹配的词，以及 skill 是否真的同步到了 agent 的配置目录（用skills doctor可以诊断）。

5. 多 agent 协同：Claude Code 与 Cursor 共享技能库

5.1 两个工具的 skill 加载机制差异

Claude Code 和 Cursor 虽然都支持 agent-skills，但加载机制有细微差别，这点必须搞清楚，否则会出现"在 A 里好用，在 B 里不触发"的情况。

Claude Code 的加载是基于目录扫描的。它启动时会扫描配置目录下的所有 skill 文件，全部加载进上下文。这意味着 skill 数量多了会占用不少 token。我的经验是控制在 20 个以内，超过之后响应速度会明显下降。

Cursor 的加载是基于索引匹配的。它只加载 skill 的 frontmatter 部分建立索引，真正用到某个 skill 时才加载正文。这个机制更省 token，但对 description 和 triggers 的质量要求更高——索引匹配不准，skill 就永远不会被加载。

理解了差异，配置策略就清晰了：共享的 skill 要保证 description 和 triggers 写得足够精准，这样在两种机制下都能正确命中。

5.2 配置双端同步

在skills.config.json里把 agent 配成数组：

{ "agent": ["claude-code", "cursor"], "skillDir": "./.agent-skills/skills", "autoSync": true }

然后跑一次全量同步：

skills sync --all

CLI 会自动把 skill 分发到两个工具各自的配置目录。Claude Code 那边是~/.claude/skills/，Cursor 那边是~/.cursor/skills/（具体路径以你安装的版本为准，用skills doctor可以打印出实际路径）。

5.3 处理工具特有的 skill

有些 skill 是某个工具专属的。比如 Cursor 的 Tab 补全相关操作，在 Claude Code 里没有对应概念。这种情况用agent字段在 skill 级别覆盖全局配置：

--- name: cursor-tab-hint description: 优化 Cursor Tab 补全的上下文提示 version: 1.0.0 agent: cursor ---

这样这个 skill 只会同步到 Cursor，不会污染 Claude Code 的上下文。

实操心得：我建议把 skill 分成三层——通用层（两个工具都用）、工具层（单工具专属）、项目层（当前项目专属）。通用层放全局配置目录，项目层放项目内的.agent-skills/skills/，工具层用 agent 字段区分。这样结构清晰，迁移项目时只带走项目层即可。

6. 常见问题排查与避坑实录

6.1 skill 不触发怎么办

这是最高频的问题。排查顺序我整理成了一张表：

我遇到最多的是第一种。CLI 装好了但忘了 sync，agent 那边根本没看到 skill。养成习惯：每次改完 skill 就跑一次skills sync，或者把autoSync打开。

6.2 token 消耗异常增大

如果你发现 agent 响应变慢、成本上升，八成是 skill 加载太多。用这个命令看每个 skill 的 token 占用：

skills stats --tokens

输出会列出每个 skill 的 frontmatter 和正文分别占多少 token。正文超过 500 token 的 skill 就要考虑精简了。我的做法是把长 skill 拆成"主 skill + 引用文件"，主 skill 只放流程，详细规范放到单独的引用文件里，agent 需要时才读。

6.3 团队协作时的版本冲突

多人维护 skill 库时，最容易出问题的是同一个 skill 被两个人改了不同版本。解决办法是给 skill 加版本号，并且用 Git 管理 skill 目录。

cd .agent-skills git init git add . git commit -m "chore: init skill library"

然后推到团队仓库。每个人改 skill 都走 PR 流程，review 通过才合并。CLI 的registry.json会记录每个 skill 的版本和来源，skills update时会检查冲突。

6.4 几个我踩过的具体坑

坑一：skill 名字用了大写。CLI 在 Linux 和 macOS 上对大小写敏感，Windows 上不敏感。你在 Windows 上测试通过的 skill，到 CI 的 Linux 环境里可能就找不到了。统一用小写加连字符，别偷懒。

坑二：frontmatter 里的冒号没转义。description 里如果写了按规范: 提交代码，YAML 解析会报错。要么用引号包起来，要么把冒号换成其他标点。这个错误很隐蔽，CLI 报的错也不直观，我第一次遇到排查了半小时。

坑三：依赖循环。skill A 依赖 B，B 又依赖 A，CLI 安装时会死循环。写依赖前先在纸上画一下依赖图，确保是有向无环的。

坑四：把敏感信息写进 skill。有人在 skill 里写了内部 API 地址、测试账号密码，然后提交到了公开仓库。skill 文件是要进版本控制的，任何敏感信息都不该出现在里面。需要配置的用环境变量，在 skill 正文里写"从环境变量 XXX 读取"。

7. 进阶玩法：把 skill 库做成团队资产

7.1 skill 的粒度怎么把握

这是我在团队里推行时被问最多的问题。粒度太粗，一个 skill 干太多事，复用性差；粒度太细，skill 数量爆炸，管理成本高。

我的判断标准是：一个 skill 对应一个"可以独立完成、有明确输入输出"的操作。"生成提交信息"是合格的粒度，"写代码"就太粗，"在提交信息里加 emoji"就太细。

实际操作中，我会先按"操作频率"筛一遍。每周至少用三次的操作，才值得做成 skill。低频操作直接手打 prompt 就行，做成 skill 反而是负担。

7.2 skill 的组合模式

skill 之间除了依赖，还有几种组合模式值得掌握。

串行组合：skill A 的输出是 skill B 的输入。比如"生成变更日志"skill 的输出，作为"发布说明"skill 的输入。这种用 dependencies 声明即可。

条件组合：根据任务类型选择不同的 skill。比如"代码审查"skill 内部判断语言，然后调用对应的语言规范 skill。这种在 skill 正文里写判断逻辑。

并行组合：多个 skill 同时作用于一个任务。比如"提交代码"时同时触发"代码检查"和"提交信息生成"。这种靠 triggers 的匹配，agent 会自己协调。

7.3 用 skill 固化团队规范

这是 agent-skills 最有价值的应用场景。团队里那些"口头约定"的规范，比如"提交信息必须关联 issue 编号""新增接口必须写文档注释""数据库变更必须写迁移脚本"，过去靠 code review 时人工检查，现在可以固化成 skill，让 agent 在生成代码时就遵守。

我帮一个团队做过这件事，流程是这样的：先把现有规范文档整理出来，然后逐条判断"这条能不能转成 agent 可执行的步骤"。能转的写成 skill，不能转的（比如"代码要有可读性"这种主观标准）保留人工 review。最后沉淀了 12 个 skill，新人入职第一天就能用上团队的规范，code review 的返工率明显下降。

7.4 持续维护的节奏

skill 库不是建完就完事的，需要持续维护。我给自己定的节奏是：每月 review 一次，看哪些 skill 从没被触发过（说明 triggers 写得不好或者根本不需要），哪些 skill 经常触发但效果不好（说明正文需要优化）。

skills stats命令能给出每个 skill 的触发次数和成功率，这是维护的主要依据。触发次数为零的 skill，要么删掉，要么重写 triggers。成功率低的 skill，重点看正文的步骤描述是不是不够具体。

提示：skill 库的维护成本会随着数量增长而上升。我的经验是控制在 30 个以内，超过之后就要考虑分层——把不常用的归档，只在特定项目里按需加载。

8. 关于 agent-skills 的一些个人体会

用这套东西大半年，最大的感受是：它改变的不是 agent 的能力上限，而是你使用 agent 的方式。模型本身能做的事没变，但你把操作知识沉淀下来之后，每次交互的起点变高了，不用再从零解释背景。

另一个体会是，skill 的质量比数量重要得多。我见过有人一口气装了五十个 skill，结果 agent 每次响应都慢半拍，还经常触发错误的 skill。后来砍到十五个，体验反而好了。少而精，是这套工具的正确打开方式。

最后分享一个我最近在试的玩法：把 skill 和项目的 CI 流程打通。比如提交前自动跑一遍 skill 里定义的检查项，检查不通过就不让提交。这样 skill 不只是"指导 agent"，还变成了"约束人"的规范。这个方向还在摸索，等跑顺了再单独写一篇。