agent-skills 实战：用 skills CLI 为 Claude Code 打造标准化技能包

1. 从"agent-skills"这个标题能读出什么

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 的能力拆成可复用模块的工程化尝试。关键词里同时出现了skills CLI、Claude Code、test-driven-development，这三者放在一起，指向一个很具体的场景——把"让 AI 写代码"这件事，从"每次靠嘴描述需求"升级成"给 agent 装上一套标准化的技能包"。

说白了，大多数人用 AI 编程工具的方式还停留在"对话式"：打开终端或者编辑器插件，敲一段需求，等它吐代码，不满意就再补一句。这种方式在写一个函数、改一个 bug 的时候够用，但一旦项目变大、需求变复杂，问题就暴露了——agent 不知道你的代码规范、不知道你的测试习惯、不知道你项目里那些约定俗成的目录结构，每次都要重新解释一遍，效率极低。

agent-skills想解决的就是这个"重复解释"的问题。它把常见的开发任务抽象成一个个 skill（技能），每个 skill 是一份结构化的说明文档，告诉 agent 在特定场景下应该遵循什么流程、产出什么格式、注意哪些边界。配合skills CLI这样的命令行工具，你可以把这些技能安装到 Claude Code 这类 agent 环境里，让它在你需要的时候自动加载对应的能力。

这篇文章适合三类人看：一是已经在用 Claude Code 或者类似 AI coding agent、但觉得"它总是不按我的套路来"的开发者；二是想给自己的团队建立一套 AI 辅助开发规范的技术负责人；三是对 agent 工程化感兴趣、想搞清楚"skills 到底是个什么东西"的探索者。我会从概念拆解讲到实操落地，把我在配置和使用过程中踩过的坑一并说清楚。

2. agent-skills 到底解决了什么问题

2.1 传统 AI 编程的"上下文失忆"困境

用 AI coding agent 写代码，最让人抓狂的不是它写不出来，而是它写出来的东西"不像你写的"。你项目里用的是特定的错误处理模式、特定的日志格式、特定的测试框架配置，但 agent 默认按它训练数据里最常见的写法来，结果就是每次生成完你都要手动改一遍。

这个问题的本质是上下文缺失。agent 每次启动都是"失忆"状态，它不知道你的项目历史、不知道你的团队约定、不知道你上一次为什么否定了它的方案。你当然可以在对话里把这些都告诉它，但这就变成了"每次都要重新培训一个新员工"。

agent-skills的思路是把这些"培训内容"固化下来。一个 skill 本质上就是一份写给 agent 看的操作手册，里面规定了：这个任务什么时候触发、执行步骤是什么、产出物长什么样、有哪些禁忌。比如一个test-driven-development技能，会明确告诉 agent"先写测试、再写实现、最后重构"这个循环，而不是让它自由发挥。

2.2 skills 与普通 prompt 模板的本质区别

很多人会问：这不就是 prompt 模板吗？我存几个常用的提示词不就行了？

区别在于触发机制和结构化程度。普通 prompt 模板需要你手动复制粘贴，而且是一坨文本，agent 只能整体理解。而 skill 是结构化的，通常包含元数据（名称、描述、触发条件）和正文（具体指令），skills CLI这类工具能根据当前任务自动匹配并加载对应的 skill。

打个比方：prompt 模板像是你桌上的一叠便签，用的时候自己翻；skill 像是给 agent 装的一个"技能插件"，它在遇到相关任务时会自动调用。前者靠人，后者靠系统。

2.3 为什么是现在：AI coding agent 的工程化拐点

这个仓库出现的时机很有意思。2024 年到 2025 年，AI coding agent 从"玩具"变成了"生产力工具"，Claude Code、Cursor、各种 CLI agent 层出不穷。但工具能力上来了，配套的"使用规范"却没跟上。大家都在摸索怎么让 agent 更听话，agent-skills代表了一种方向：不改变模型本身，而是通过外挂知识库的方式，让 agent 的行为可预测、可复用、可传承。

这对团队协作尤其重要。一个资深工程师调教好的 agent 使用方式，如果能沉淀成 skill，新来的同事直接安装就能用，不用从头摸索。这是把个人经验变成团队资产的过程。

3. skills CLI 的安装与核心命令拆解

3.1 环境准备：Node 版本与包管理器选择

skills CLI是个 Node 工具，安装前先确认环境。我实测下来，Node 18 以上比较稳，Node 20 LTS 是最省心的选择。如果你用的是 macOS，建议用nvm管理 Node 版本，避免系统自带的旧版本捣乱。

# 检查当前 Node 版本 node -v # 如果低于 18，用 nvm 装一个 LTS nvm install 20 nvm use 20

包管理器方面，npm、pnpm、yarn 都能用，但我个人偏好 pnpm，原因是它装全局包的时候磁盘占用小、速度快。不过如果你只是偶尔用一下，npm 也完全够，没必要为了这个专门换工具链。

提示：如果你在公司内网环境，npm 源可能需要换成内部镜像，否则安装会卡住。这个具体怎么配得看你们公司的规范，我不展开。

3.2 全局安装与版本验证

安装命令很直接：

# 用 npm npm install -g skills-cli # 或者用 pnpm pnpm add -g skills-cli

装完之后验证一下：

skills --version

如果提示command not found，八成是全局 bin 目录没加到 PATH 里。npm 的话可以用npm config get prefix看看全局路径在哪，然后手动加进环境变量。这个问题在 Ubuntu 上特别常见，因为默认的 npm 全局路径有时候不在 PATH 里。

3.3 常用子命令一览与使用场景

skills CLI的命令设计得比较克制，核心就几个：

我一般的工作流是：先search找到想要的，再info看一眼具体内容确认符合预期，最后install。别小看info这一步，有些 skill 的触发条件写得很宽泛，装多了会互相干扰，提前看清楚能省不少事。

3.4 技能安装目录与项目级 vs 全局级

这里有个容易踩的坑：skill 装在哪一级。skills CLI通常支持全局安装（对所有项目生效）和项目级安装（只对当前项目生效）。全局的适合那些通用技能，比如代码审查、提交信息生成；项目级的适合跟具体技术栈绑定的，比如某个框架的特定写法。

项目级安装一般会在项目根目录生成一个配置目录（类似.skills/这种），记得把它加进版本控制，这样团队其他人拉下来就能用同一套技能。全局的则存在用户目录下，换机器要重新装。

注意：如果你在多个项目间切换，全局装了一堆技能，可能会出现"这个项目的 agent 突然按另一个项目的规范写代码"的诡异情况。我的建议是通用技能全局装，专用技能一律项目级。

4. 把 skills 接入 Claude Code 的完整流程

4.1 Claude Code 的安装方式选择

在讲接入之前，先说说 Claude Code 本身怎么装。目前主流有几种方式：官方 CLI、VS Code 插件、桌面版。我三种都用过，说下各自的适用场景。

官方 CLI 最灵活，适合习惯终端操作的人，能直接执行终端命令，跟 skills 的配合也最顺。VS Code 插件的好处是跟编辑器集成，改代码的时候不用切窗口。桌面版适合不想碰命令行的用户，但灵活性差一些。

安装 CLI 的话，macOS 和 Ubuntu 的步骤略有不同。macOS 上一般用官方提供的安装脚本或者包管理器，Ubuntu 上要注意权限问题，可能需要sudo或者配置用户级安装路径。装完之后用claude --version验证。

4.2 让 skills 被 agent 识别的配置要点

装好 Claude Code 和 skills CLI 之后，关键一步是让 agent 知道去哪找技能。这通常涉及一个配置文件，告诉 Claude Code"技能目录在哪"。

配置的核心逻辑是：Claude Code 启动时会读取某个约定位置的技能定义，把它们作为可用工具或者上下文注入。具体路径和格式取决于版本，但思路是一样的——你得让 agent 在启动时"看到"这些技能。

我踩过的一个坑是：技能装了但 agent 不认。排查下来发现是配置文件里的路径写的是相对路径，而 agent 的工作目录跟我预期的不一样。改成绝对路径就解决了。所以配置路径的时候，能用绝对路径就别用相对的。

4.3 验证技能是否生效的三种方法

装完配置完，怎么确认真的生效了？我总结了三个办法：

1. 直接问 agent：在对话里问"你现在有哪些可用技能"，看它列出来的清单里有没有你刚装的。
2. 触发测试：故意做一个应该触发该技能的任务，观察 agent 的行为是否符合技能定义。比如装了 TDD 技能，就让它写个新功能，看它是不是先写测试。
3. 看日志：Claude Code 一般有调试模式，能看到它加载了哪些上下文。这个最准确，但需要你会看日志。

三种方法我建议结合用，尤其是第二种，因为"技能被加载"和"技能被正确执行"是两回事。

4.4 多模型环境下的技能兼容性

现在很多人不只用 Claude 官方模型，还会通过第三方 API 接入其他模型。这里要注意：skills 本质上是提示词工程，不同模型对同一份技能说明的理解能力不一样。有些技能在 Claude 上跑得很好，换到别的模型可能就"理解偏了"。

我的经验是，技能说明写得越具体、越结构化，跨模型的兼容性越好。那些依赖模型"悟性"的模糊描述，换个模型就废了。所以如果你打算多模型混用，skill 的写法要偏"指令式"而不是"引导式"。

5. 用 test-driven-development 技能跑通第一个闭环

5.1 为什么选 TDD 作为入门技能

test-driven-development是关键词里明确提到的技能，也是最适合拿来验证 skills 机制的一个。原因很简单：TDD 有明确的、可观察的行为特征——先写测试、测试失败、写实现、测试通过、重构。这五个步骤如果 agent 真的按技能执行了，你一眼就能看出来。

相比之下，像"代码审查"这种技能，产出质量好坏比较主观，不容易判断技能到底有没有起作用。TDD 是天然的验证场景。

5.2 技能触发后的实际行为观察

我拿一个真实的小需求测试：给一个已有的工具函数加参数校验。装了 TDD 技能之后，agent 的行为明显变了。

没装技能时，它会直接改函数体，加上 if 判断，然后告诉你"改好了"。装了技能后，它先问我要不要写测试，然后生成一个测试文件，里面是针对参数校验的测试用例，跑一遍确认失败，再改实现，最后再跑一遍确认通过。

这个行为差异非常明显。它不再是"给我结果"，而是"走流程"。这就是 skill 的价值——把方法论固化进 agent 的行为模式。

5.3 测试用例生成质量的调优

不过默认的 TDD 技能生成的测试用例质量参差不齐。常见问题是：只测正常路径，不测边界条件；断言写得太宽松，测了等于没测。

我的调优办法是在技能基础上再加一层项目级的补充说明，明确要求"每个函数至少覆盖正常值、边界值、异常输入三类用例"。这个补充可以写在项目的技能配置里，也可以直接在对话里强调。实测下来，加了这条约束之后，测试覆盖率明显提升。

5.4 从"能跑"到"好用"的迭代思路

第一个闭环跑通只是开始。真正让 skills 产生价值，需要持续迭代。我的做法是：每次 agent 的行为不符合预期，就回头改 skill 的定义，而不是每次在对话里临时纠正。改完 skill，下次它就记住了。

这个过程有点像带新人——你不能指望说一次他就永远记住，但你可以把要求写进 SOP，让他照着做。skill 就是 agent 的 SOP。

6. 技能编写与自定义的实战经验

6.1 一个 skill 的最小结构

自己写 skill 其实不难，最小结构就三部分：元数据、触发条件、执行指令。元数据包括名称和描述，触发条件说明什么情况下该用这个技能，执行指令是具体的步骤。

--- name: my-custom-skill description: 当需要处理 XXX 任务时使用 --- ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 产出物格式要求

关键在"触发条件"要写得精准。写太宽，技能到处触发，干扰正常流程；写太窄，该触发的时候不触发，等于没装。

6.2 触发条件怎么写才精准

我的经验是用"任务特征"而不是"关键词"来定义触发条件。比如不要写"当用户提到测试时触发"，而要写"当任务涉及新增功能或修改现有逻辑，且项目配置了测试框架时触发"。前者太泛，后者有明确的场景边界。

另外，多个技能之间的触发条件要避免重叠。如果两个技能都声称处理"代码质量"，agent 就不知道该用哪个。这时候要么合并，要么把边界划清楚。

6.3 把团队规范翻译成技能描述

这是我觉得 skills 最有价值的地方。每个团队都有自己的规范：提交信息格式、分支命名规则、代码审查清单。这些以前靠文档和口头传承，现在可以写成 skill。

翻译的时候要注意：规范文档是写给人看的，skill 是写给 agent 看的。人能从上下文推断的东西，agent 不一定能。所以 skill 要写得更"笨"一点，把隐含的前提都显式说出来。比如"提交信息用祈使句"这种，要补充例子，否则 agent 可能理解成各种样子。

6.4 技能冲突与优先级处理

装多了技能，冲突是必然的。两个技能对同一件事有不同要求，agent 就懵了。处理办法有两个：一是合并冲突的技能，二是明确优先级。

优先级可以通过技能配置里的顺序或者显式的优先级字段来控制。我的建议是尽量合并，因为优先级机制依赖 agent 正确理解，不如直接消除冲突来得可靠。

7. 踩坑记录：那些文档里不会写的问题

7.1 技能装了但 agent "视而不见"

这是最常见的坑。原因通常有三个：路径配置错误、技能格式不符合规范、agent 版本不支持该技能机制。排查顺序建议从路径开始，因为最容易错也最容易改。

我遇到过一次是技能文件的 frontmatter 格式有问题，YAML 里多了个空格导致解析失败，但 CLI 不报错，agent 也不提示，就是静默不加载。后来用skills info才发现元数据没读出来。所以装完技能一定要用info确认元数据解析正常。

7.2 多项目环境下技能串味

前面提过，全局技能和项目技能混用会导致串味。具体表现是：在 A 项目里 agent 按 B 项目的规范写代码。这个问题的根源是技能加载顺序和覆盖规则不清晰。

我的解决方案是：全局只装跟技术栈无关的通用技能（比如提交信息规范），所有跟具体项目相关的技能一律项目级安装，并且在项目配置里显式声明"只加载本项目技能"。这样虽然每个项目要单独配，但避免了串味。

7.3 技能更新后的缓存问题

技能更新了，但 agent 还在用旧版本。这是缓存导致的。skills CLI一般有缓存机制，更新技能后需要手动刷新或者重启 agent。

我养成的习惯是：每次更新技能后，先skills list确认版本变了，再重启 Claude Code。别嫌麻烦，不然你会对着"为什么改了没生效"困惑半天。

7.4 与第三方 API 模型配合时的注意事项

用第三方 API 接入其他模型时，skills 的效果会打折扣。原因是这些模型对结构化指令的遵循能力不如官方模型。我的应对策略是：把技能说明写得更短、更直接，减少需要"理解"的部分，增加"照做"的部分。

另外，第三方 API 的上下文窗口可能更小，技能装太多会挤占正常对话的空间。这种情况下要精简技能，只留最核心的几个。

8. 关于 agent-skills 的一些个人判断

用了一段时间下来，我对agent-skills这类工具的判断是：它代表了 AI 辅助开发从"个人技巧"走向"工程规范"的方向，但现在还处于早期。技能生态不够丰富，编写规范也没统一，不同工具之间的技能还不能互通。

但方向是对的。当 AI coding agent 越来越强，瓶颈就从"模型能力"转移到了"如何让模型按我的方式工作"。skills 就是解决这个瓶颈的一种尝试。它不一定是最优解，但至少提供了一条可操作的路径。

我现在的做法是：把团队里反复出现的、有明确流程的开发任务，逐步沉淀成 skill。不追求一次写完美，而是用一次改一次。这个过程本身也是在梳理团队的开发规范，一举两得。

如果你刚开始接触，建议从test-driven-development这种行为特征明显的技能入手，先跑通一个闭环，建立对 skills 机制的直观理解，再考虑自己写。别一上来就搞一堆自定义技能，那样只会把自己绕进去。