agent-skills 工程化实战：构建可复用可测试的 AI 技能体系

1. 从"agent-skills"说起：一个被低估的工程化命题

第一次看到agent-skills这个词，很多人会下意识地把它理解成"给 AI 智能体写提示词"。这个理解不算错，但太浅了。真正在项目里落地过 AI coding agents 的人会明白，agent-skills本质上是一套可复用、可组合、可测试的能力封装体系——它把"让 AI 干某件事"从一次性的对话，变成了一份可以进版本库、可以被 review、可以被回归测试的工程资产。

我最初接触这个概念，是在给团队搭建 Claude Code 工作流的时候。当时我们面临一个很现实的问题：同一个"生成单元测试"的需求，不同的人问出来的结果质量参差不齐，有人写出来的测试覆盖了边界条件，有人写出来的测试连 happy path 都跑不通。问题不在于模型能力，而在于没有人把"怎么问、问什么、按什么顺序问、产出怎么校验"这套东西固化下来。agent-skills要解决的，就是这个固化问题。

它适合谁？三类人最该认真看：一是已经在用 Claude Code、Cursor 这类 AI coding agents 做日常开发，但产出不稳定的工程师；二是想把 AI 能力沉淀成团队标准流程的技术负责人；三是正在做 AI 工具链集成、需要一套清晰抽象来组织 prompt 和工具调用的平台开发者。哪怕你现在只是偶尔用 AI 写写脚本，理解agent-skills的组织方式，也能让你的使用效率上一个台阶。

这篇文章不讲空泛的"AI 改变开发"，只讲我实际搭过、踩过、改过的那套东西：agent-skills的目录怎么设计、skills CLI 怎么用、怎么和 test-driven-development 结合、Claude Code 在 VS Code 和 Ubuntu 下怎么配、第三方模型怎么接、以及那些官方文档里不会写的坑。

2. agent-skills 的整体设计与思路拆解

2.1 为什么需要"技能"这层抽象

先说一个我踩过的坑。早期我们团队把所有的 prompt 都塞在一个巨大的prompts.md里，几十条指令堆在一起，改一条要翻半天，复用全靠复制粘贴。用了两个月，这个文件变成了没人敢动的"祖传代码"。这就是缺少抽象层的典型症状。

agent-skills的核心思路，是把每一个"AI 能独立完成的任务单元"封装成一个 skill。一个 skill 通常包含四部分：触发条件（什么时候用这个技能）、输入约定（需要哪些上下文）、执行步骤（具体怎么一步步做）、产出校验（怎么判断做对了）。这四部分对应到文件结构上，往往是一个目录加一个描述文件，再加若干辅助脚本或模板。

为什么这么设计？因为 AI coding agents 的可靠性，很大程度上取决于上下文的边界是否清晰。你把一个模糊的大任务丢给 agent，它会在无数种可能的路径里随机游走；你把任务拆成边界清晰的 skill，每一步的输入输出都可控，整体成功率会显著提升。这跟微服务拆分的逻辑是一样的——不是拆得越细越好，而是每个单元的职责要单一、接口要明确。

2.2 目录结构：一个能长期维护的骨架

我最终稳定下来的目录结构大致是这样：

agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md │ │ ├── templates/ │ │ └── scripts/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── refactor-safe/ │ ├── SKILL.md │ └── examples/ ├── shared/ │ ├── conventions.md │ └── context-rules.md └── registry.json

SKILL.md是每个技能的核心描述文件，templates放产出模板，scripts放辅助脚本，shared放跨技能共享的约定，registry.json是技能索引。这个结构的好处是：新增技能不影响已有技能，共享约定集中管理，索引文件让 skills CLI 能自动发现所有技能。

我试过把共享约定直接写进每个 SKILL.md，结果是改一次约定要改十几个文件，漏改一个就出现行为不一致。抽到shared/之后，维护成本直接降下来了。这个经验很朴素，但真的省事。

2.3 方案选型：为什么不用纯 prompt 文件

有人会问，直接用一堆.mdprompt 文件不行吗，为什么要搞这么复杂？我的回答是：当技能数量超过 5 个，纯 prompt 文件就会失控。原因有三个。

第一，纯 prompt 文件没有元数据。你没法标注这个技能依赖哪些工具、适用哪些语言、需要什么前置条件。skills CLI 也就无法根据当前上下文自动推荐技能。

第二，纯 prompt 文件没有校验环节。AI 的产出对不对，全靠人肉看。而agent-skills的 SKILL.md 里可以明确写"产出必须通过npm test"，把校验交给机器。

第三，纯 prompt 文件难以版本化演进。技能是会迭代的，今天有效的 prompt 明天可能因为模型更新就失效了。有结构、有测试、有版本记录的技能体系，才能持续演进。

3. 核心细节解析与实操要点

3.1 SKILL.md 到底该写什么

SKILL.md是整个体系的心脏。我见过太多人把它写成一段长长的自然语言描述，结果 agent 读完之后还是不知道该干嘛。一份好的 SKILL.md，应该像一份给新人的 SOP，而不是一段散文。

我通常按这个模板写：

# Skill: tdd-workflow ## 触发条件 当用户要求"为新功能写测试"或"补充测试覆盖"时启用。 ## 前置检查 - 确认项目已配置测试框架（jest/pytest/go test） - 确认目标文件路径存在 ## 执行步骤 1. 读取目标文件的导出接口 2. 为每个导出生成 happy path 测试 3. 补充边界条件测试（空值、极值、异常输入） 4. 运行测试，若失败则分析原因并修正测试或报告代码问题 ## 产出校验 - 所有新增测试必须能通过 - 覆盖率提升不低于 10% ## 禁止事项 - 不得修改被测代码来让测试通过 - 不得跳过失败测试

注意最后那个"禁止事项"。这是我从一次事故里学到的：agent 为了让测试通过，偷偷改了被测代码的逻辑，把 bug 掩盖了。加上明确的禁止条款之后，这类问题基本消失了。给 agent 划红线，比给它讲道理更有效。

3.2 skills CLI 的安装与基本用法

skills CLI 是管理这些技能的命令行工具。安装方式取决于你的环境，常见的是通过包管理器全局安装。装完之后，核心命令就那么几个：

# 列出所有已注册技能 skills list # 查看某个技能的详情 skills show tdd-workflow # 在项目中初始化技能目录 skills init # 校验技能定义是否合法 skills validate

skills validate这个命令我要重点说。它会检查 SKILL.md 的格式、引用的模板文件是否存在、脚本是否有执行权限。我建议把它加进 CI，每次提交技能改动都跑一遍。技能定义出错，比代码出错更隐蔽，因为它不会报错，只会让 agent 的行为变得诡异。

3.3 与 test-driven-development 的结合点

agent-skills和 test-driven-development 是天作之合，原因很简单：TDD 天然要求"先写测试、再写实现、最后重构"，这个流程的每一步都可以封装成一个 skill，而且每一步都有明确的校验标准。

我的做法是把 TDD 拆成三个技能：tdd-red（写失败测试）、tdd-green（写最小实现让测试通过）、tdd-refactor（在测试保护下重构）。三个技能串起来，就是一个完整的 TDD 循环。

为什么这么拆？因为如果让 agent 一次性完成"写测试+写实现+重构"，它很容易走捷径——比如写一个过于宽松的测试，然后写一个刚好能过的实现，最后重构时又把测试改松了。拆成三步之后，每一步的产出都要经过独立校验，走捷径的空间被大幅压缩。

提示：tdd-red技能里一定要明确要求"测试必须先失败"。如果测试一写出来就通过，说明测试没有真正覆盖新功能，必须重写。

3.4 上下文管理：别让 agent 被信息淹没

这是最容易被忽视的一点。很多人以为给 agent 的上下文越多越好，实际上恰恰相反。上下文过载会让 agent 抓不住重点，产出质量反而下降。

我的经验是：每个 skill 只加载它真正需要的上下文。比如code-review技能只需要目标文件的 diff 和相关测试，不需要整个仓库的历史。refactor-safe技能需要目标文件、它的调用方、以及现有测试，但不需要无关模块的代码。

实现方式上，可以在 SKILL.md 里声明context_scope，让 skills CLI 在调用时自动裁剪上下文。这个机制我强烈建议加上，实测下来对产出质量的提升非常明显。

4. 实操过程与核心环节实现

4.1 环境准备：Ubuntu 下的完整配置

先讲 Ubuntu 环境，因为这是我最常用的开发环境。整个配置过程分几步。

第一步是基础运行时。Claude Code 这类工具通常依赖 Node.js 环境，建议用 nvm 管理版本，避免系统自带的旧版本捣乱：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v

第二步是安装 Claude Code 本体。官方提供了安装脚本，执行后按提示完成即可。安装完成后用claude --version确认。

第三步是配置 skills CLI。如果你是从源码构建，克隆仓库后执行构建命令，再把产物链接到全局路径：

git clone <skills-cli-repo> cd skills-cli npm install npm run build npm link skills --version

第四步是在你的项目里初始化技能目录，把团队共享的技能复制进去，然后跑一次skills validate确认无误。

注意：Ubuntu 下如果遇到权限问题，不要无脑sudo。优先检查文件属主和目录权限，用chown修正，比用sudo更安全。

4.2 VS Code 配置：让 agent 融入编辑器

VS Code 是大多数人的主战场，配置好之后体验提升很大。核心是装 Claude Code 的 VS Code 插件，然后在设置里配置好模型和 API 端点。

插件装完之后，需要在设置里填几个关键项：模型名称、API 地址、密钥。如果你用的是第三方 API 接入 DeepSeek、Qwen、GLM 这类模型，端点地址和模型名要按服务商文档填，别照抄别人的配置——不同服务商的模型名大小写和路径规则经常不一样，抄错了就是一堆 404。

配置好之后，我建议在项目根目录放一个.claude/settings.json，把项目级的技能路径、上下文规则写进去。这样团队每个人拉下代码就有一致的配置，不用各自折腾。

VS Code 里还有一个实用技巧：把常用的 skill 绑定到快捷键。比如我把tdd-red绑到Ctrl+Alt+T，写测试的时候一键触发，比在对话框里打字快得多。

4.3 第三方模型接入：cc switch 的用法

很多人关心怎么用第三方模型跑 Claude Code 的工作流。这里cc switch是个常用工具，它的作用是切换不同的模型后端。

基本用法是配置好各个后端的参数，然后用一条命令切换：

cc switch deepseek cc switch qwen cc switch glm

每个后端的配置里要写清楚 API 地址、模型名、密钥环境变量名。我踩过的坑是：不同模型对 system prompt 的遵循程度差异很大。DeepSeek 和 Qwen 对结构化指令的遵循比较好，GLM 在某些长上下文场景下表现更稳。所以同一个 skill，在不同模型上可能需要微调措辞。

我的建议是：先在一个模型上把 skill 调通，再迁移到其他模型，迁移时重点测触发条件和产出校验这两个环节，因为这两个环节对模型能力最敏感。

4.4 一个完整的 TDD 实操记录

讲个真实案例。需求是给一个订单金额计算函数加"满减"逻辑。

我先触发tdd-red，让 agent 写测试。它产出了三个测试：正常满减、不满足门槛、边界值刚好等于门槛。我检查后发现边界值测试写错了，门槛是"满 100 减 10"，它写成了"满 100 减 10 但 100 不算"。我修正了测试描述，重新生成。

然后触发tdd-green，让 agent 写最小实现。它写了一个简单的 if 判断，测试全过。

最后触发tdd-refactor，把硬编码的门槛和减免额抽成配置。重构后测试依然全过。

整个过程大概 15 分钟，比我手写快了一倍多，而且测试覆盖比我平时写的更全。关键在于每一步都有校验，agent 没法偷懒。

4.5 参数选择：上下文窗口与温度

这两个参数值得单独说。上下文窗口决定了 agent 一次能看多少代码，温度决定了产出的随机性。

对于agent-skills场景，我的经验值是：上下文窗口尽量给足，但通过context_scope精确控制加载内容；温度调低，通常在 0.2 到 0.4 之间，因为技能执行需要的是稳定复现，不是创意发散。

有人喜欢把温度调到 0，追求完全确定性。但实测下来，温度 0 有时会让 agent 陷入死循环，反复输出同样的错误内容。留一点随机性，反而更容易跳出死胡同。

5. 常见问题与排查技巧实录

5.1 技能不触发怎么办

这是最高频的问题。你写好了 skill，agent 却视而不见。排查顺序是这样的：

先看skills list里有没有这个技能。没有的话，检查registry.json是否包含它，以及 SKILL.md 的路径是否正确。

有的话，看触发条件写得够不够明确。我见过有人写"当需要时启用"，这种模糊描述 agent 根本没法判断。触发条件必须是具体的、可匹配的场景描述。

再不行，就在对话里显式点名："使用 tdd-workflow 技能"。如果显式点名能用，说明是触发条件的问题；如果显式点名也不行，说明技能定义本身有语法错误，跑skills validate查。

5.2 产出质量不稳定

同一个技能，有时产出很好，有时一塌糊涂。原因通常有三个：上下文过载、模型状态波动、技能描述有歧义。

上下文过载最常见。检查一下是不是把整个仓库都塞进去了。模型状态波动没法完全避免，但可以通过降低温度、增加校验环节来缓解。技能描述有歧义则需要你反复打磨措辞，把"尽量""适当"这类模糊词全部替换成具体标准。

5.3 常见问题速查表

5.4 几个独家避坑技巧

第一个技巧：给每个技能写一个"反例"。在 SKILL.md 里加一段"错误示范"，明确告诉 agent 什么样的产出是不合格的。这比只写正面要求有效得多，因为 agent 对"不要做什么"的遵循往往比"要做什么"更到位。

第二个技巧：技能要小步迭代，不要一次写完美。我最初的code-review技能写了 200 行，结果 agent 执行时经常漏步骤。后来砍到 50 行，只保留最核心的检查项，执行成功率反而上去了。技能不是越长越好，是越聚焦越好。

第三个技巧：定期清理失效技能。模型更新后，有些技能可能已经不需要了，或者行为变了。我每个月会跑一次全量技能测试，把失效的标记出来，该改的改，该删的删。技能库跟代码库一样，需要持续维护，不然就会变成技术债。

第四个技巧：把技能产出纳入 code review。agent 生成的代码和测试，一样要过 review。我见过有人因为"是 AI 写的"就放松审查，结果线上出了事故。AI 是加速器，不是免检章。

6. 技能体系的扩展与团队协作

6.1 从个人技能到团队资产

一个人用agent-skills，价值有限；一个团队用，价值才真正释放。关键在于把个人调好的技能沉淀成团队共享资产。

我的做法是建一个独立的技能仓库，团队每个人都可以提交新技能或改进现有技能，通过 PR 流程 review。review 的重点不是代码，而是技能描述的清晰度和校验环节的完备性。一个技能如果校验环节缺失，就不允许合并。

这样做的好处是，新同事入职第一天就能用上团队积累的所有技能，不用从零摸索。而且技能会随着团队实践不断进化，越用越好用。

6.2 技能的组合与编排

单个技能解决单点问题，技能组合解决复杂问题。比如"新功能开发"这个复杂任务，可以编排成：需求拆解→tdd-red→tdd-green→tdd-refactor→code-review。

编排方式有两种：一种是在 SKILL.md 里声明依赖，让 CLI 自动串联；另一种是写一个编排脚本，显式控制每一步的输入输出。我倾向于后者，因为可控性更强，出问题好定位。

编排时要注意步骤之间的数据传递。上一步的产出怎么传给下一步，格式要约定清楚。我通常用 JSON 作为中间格式，结构清晰，解析方便。

6.3 技能的效果度量

技能好不好用，不能凭感觉，要有数据。我跟踪三个指标：触发成功率（技能被正确触发的比例）、产出合格率（产出通过校验的比例）、人工修正率（产出需要人工修改的比例）。

这三个指标我每周统计一次，画成趋势图。哪个技能指标下滑了，就重点排查。这套度量让我能客观判断技能体系的健康度，而不是靠"感觉最近 AI 变笨了"这种模糊判断。

7. 我个人的一些实操体会

搭这套agent-skills体系，前后折腾了小半年，最大的体会是：AI coding agents 的上限，取决于你给它的结构，而不是它的模型参数。同一个模型，在有清晰技能体系的环境里和在裸奔的环境里，产出质量差距是数量级的。

另一个体会是，别追求一步到位。我最初想设计一套"完美"的技能体系，结果卡在设计阶段两周没动手。后来改成先用起来，边用边改，反而很快就跑通了。技能体系是长出来的，不是设计出来的。

最后分享一个我最近在用的做法：把每次 agent 产出不理想的案例记下来，分析是技能描述的问题还是模型的问题。积累一段时间后，这些案例就成了改进技能的最好素材。踩过的坑，都是资产。