agent-skills：为AI编程助手构建可复用可测试的技能体系

1. 从“agent-skills”说起：为什么我们需要给 AI 编程助手装上“技能包”

第一次看到agent-skills这个项目名，很多人会以为它又是一个提示词合集，或者某个大模型厂商出的官方插件市场。实际上，它解决的是一个更底层、也更现实的问题：AI coding agents 很强，但它们缺少一套可复用、可组合、可测试的“技能”体系。

我最早接触 AI 编程助手是在做一个小型后端重构项目的时候。当时我让助手帮我写一个数据库迁移脚本，它给出的代码逻辑没问题，但字段类型、索引命名、回滚策略全都不符合我们团队的规范。我不得不反复在对话里补充上下文，每次新开一个会话，这些规范就全部丢失。后来我意识到，问题不在于模型不够聪明，而在于我们没有把“怎么做一件事”沉淀成 agent 可以调用的技能。

agent-skills这个项目，本质上就是在做这件事：它定义了一套技能的组织方式，让 AI coding agents 能够像人类工程师调用函数库一样，按需加载和执行特定技能。这里的“技能”不是简单的 prompt 模板，而是包含了触发条件、执行步骤、验证逻辑、失败回退的完整单元。配合skills CLI这样的命令行工具，你可以把技能安装到本地、版本化管理、甚至写测试来保证技能行为的一致性。

这篇文章适合三类人看：第一类是在日常开发中已经用上 Claude Code、Cursor、Copilot 等 AI coding agents，但觉得“每次都要重新教它”的工程师；第二类是想把团队内部规范、最佳实践固化下来，让 AI 助手自动遵守的技术负责人；第三类是对test-driven-development在 AI 辅助编程场景下如何落地感兴趣的人。我会从设计思路、核心机制、实操步骤、常见坑四个维度，把agent-skills这套东西拆开讲清楚。

需要提前说明的是，agent-skills目前并不是一个官方标准，它更像是一个社区驱动的约定和工具集合。不同 AI coding agent 对它的支持程度不一样，Claude Code 的适配相对成熟，其他工具可能需要你自己做一些桥接。但核心思想是通用的：把技能从对话历史里解放出来，变成可管理、可测试、可共享的资产。

2. 核心设计思路拆解：技能为什么不能只是提示词

2.1 从“对话式编程”到“技能式编程”的转变

大多数人用 AI coding agent 的方式是对话式的：打开终端或编辑器，输入一段需求，等它生成代码，然后根据结果继续追问。这种方式在一次性任务上效率很高，但一旦任务重复出现，问题就暴露了。

我统计过自己过去三个月在 Claude Code 里的会话记录，发现大约 40% 的对话是在重复类似的事情：写单元测试、生成 API 文档、做代码审查、处理数据库迁移。每次我都要重新描述上下文，比如“我们用的是 pytest，测试文件放在 tests 目录下，mock 用 unittest.mock，断言风格用 assert 而不是 self.assertEqual”。这些信息在每次新会话里都要重复一遍，既浪费时间，也容易遗漏。

agent-skills的思路是把这些重复性的“怎么做”抽出来，形成一个独立的技能定义。技能定义里包含几个关键部分：

• 元信息：技能名称、版本、适用场景、依赖项
• 触发条件：什么情况下应该加载这个技能，比如“当用户要求写测试时”或“当检测到 .test.js 文件时”
• 执行指令：给 agent 的具体操作步骤，可以是自然语言，也可以是结构化配置
• 验证逻辑：怎么判断技能执行成功了，比如运行测试命令、检查文件是否存在
• 回退策略：执行失败时怎么办，是重试、降级还是报错

这种结构和传统的函数定义非常像。你可以把技能理解为一个“给 AI 看的函数”，它有输入、有输出、有前置条件、有后置校验。区别在于，函数的执行者是编译器或解释器，而技能的执行者是 AI agent。

2.2 为什么选择 CLI 作为技能管理入口

skills CLI是这个项目里我最喜欢的部分。它把技能的安装、更新、卸载、列表查看做成了命令行操作，和 npm、pip、cargo 的使用体验很像。

为什么 CLI 很重要？因为 AI coding agent 的工作环境通常是终端。你在终端里跑 Claude Code，在终端里跑测试，在终端里提交代码。如果技能管理需要切换到浏览器或某个 GUI 工具，流程就断了。CLI 让技能管理成为开发工作流的一部分，而不是一个额外的负担。

我目前的用法是这样的：在项目根目录下创建一个.skills目录，里面放技能定义文件。skills CLI会读取这个目录，并根据当前会话的上下文决定加载哪些技能。比如我在写测试的时候，它会自动加载test-driven-development技能；我在做代码审查的时候，它会加载code-review技能。这种按需加载的机制，避免了把所有技能都塞进上下文导致 token 浪费。

2.3 技能与 agent 的边界在哪里

这里有一个容易混淆的点：技能和 agent 到底是什么关系？

我的理解是，agent 是执行者，技能是知识。agent 负责理解用户意图、规划任务、调用工具；技能负责告诉 agent 在特定场景下应该怎么做。一个 agent 可以加载多个技能，一个技能也可以被多个 agent 使用。

这种分离带来的好处是，你可以独立迭代技能，而不需要重新训练或微调 agent。比如你们团队的代码规范变了，只需要更新对应的技能定义，所有使用这个技能的 agent 都会自动遵循新规范。这比在每个 agent 的配置里改提示词要高效得多。

另一个好处是可测试性。技能定义是纯文本或结构化配置，你可以像测试代码一样测试技能。比如写一个测试用例，模拟 agent 在特定场景下加载技能，然后检查它生成的代码是否符合预期。这就是test-driven-development在 AI 辅助编程场景下的落地方式：先写测试定义技能应该做什么，再实现技能，最后用测试验证技能行为。

3. 核心细节解析与实操要点：技能定义怎么写才有效

3.1 技能文件的结构与字段说明

一个典型的技能定义文件通常是 YAML 或 JSON 格式，放在.skills目录下。以下是我在实际项目中常用的结构：

name: pytest-unit-test version: 1.2.0 description: 为 Python 函数生成 pytest 单元测试 triggers: - pattern: "写测试|生成测试|add tests" file_types: [".py"] - command: "pytest" dependencies: - python>=3.9 - pytest>=7.0 instructions: | 1. 读取目标函数的签名和文档字符串 2. 为每个参数生成边界值测试用例 3. 使用 unittest.mock 模拟外部依赖 4. 断言风格使用 assert，不使用 self.assertEqual 5. 测试文件命名规则为 test_<module_name>.py validation: - command: "pytest {test_file} --tb=short" expect_exit_code: 0 fallback: - action: retry max_attempts: 2 - action: report message: "测试生成失败，请检查函数签名是否完整"

这个结构里，每个字段都有明确的用途。triggers决定技能什么时候被加载，instructions是给 agent 的核心指令，validation是执行后的校验，fallback是失败处理。

我踩过的一个坑是triggers写得太宽泛。一开始我用了pattern: "test"，结果 agent 在任何包含 “test” 这个词的对话里都会加载这个技能，包括我在讨论测试策略而不是写测试的时候。后来改成更具体的模式，并且加上file_types限制，误触发的情况就少了很多。

3.2 触发条件的粒度控制

触发条件的粒度直接决定了技能加载的准确率。太宽会误触发，太窄会漏触发。我的经验是，优先使用文件类型和命令作为触发条件，自然语言模式作为辅助。

文件类型触发是最可靠的。当 agent 检测到当前操作的文件是.py时，加载 Python 相关技能；是.tsx时，加载 React 相关技能。这种触发方式几乎不会出错。

命令触发也很稳定。当 agent 准备执行pytest命令时，加载测试相关技能；准备执行docker build时，加载容器化相关技能。这种触发方式的好处是和实际工作流绑定，不会凭空触发。

自然语言模式触发最灵活，但也最容易出问题。我的建议是，如果要用模式匹配，尽量用具体的短语而不是单个词。比如用"生成单元测试"而不是"测试"，用"数据库迁移"而不是"数据库"。另外，可以给模式加上权重，多个模式同时匹配时才加载技能，这样准确率会更高。

3.3 指令编写的三个原则

instructions字段是技能的核心，它直接决定了 agent 的行为。我总结了三个编写原则：

第一，步骤要可执行，不要写“理解需求”这种模糊指令。比如不要写“根据函数逻辑生成测试”，而要写“读取函数签名，为每个参数生成至少一个正常值和一个边界值测试用例”。前者 agent 不知道具体怎么做，后者有明确的操作路径。

第二，约束要具体，不要写“遵循最佳实践”。最佳实践是什么？每个团队的理解不一样。要写“使用 assert 而不是 self.assertEqual”、“mock 外部 HTTP 调用”、“测试文件放在 tests/unit 目录下”。这些约束是可验证的，agent 执行起来不会跑偏。

第三，示例要包含，不要只写规则。人类工程师看文档的时候喜欢看示例，AI agent 也一样。在指令里附上一段输入输出的示例，agent 的生成质量会明显提升。比如：

instructions: | ... 示例： 输入函数： def add(a: int, b: int) -> int: return a + b 期望输出： def test_add_positive_numbers(): assert add(1, 2) == 3 def test_add_negative_numbers(): assert add(-1, -2) == -3 def test_add_zero(): assert add(0, 0) == 0

这个示例比任何文字描述都管用。我实测下来，加了示例之后，agent 生成的测试代码符合团队规范的比例从 60% 左右提升到了 90% 以上。

3.4 验证逻辑的设计技巧

validation是很多人会忽略的部分，但它恰恰是技能可靠性的保障。没有验证的技能，就像没有断言的测试，你永远不知道它是不是真的成功了。

验证逻辑通常是一个命令加上期望的退出码。比如测试技能验证pytest是否通过，代码审查技能验证ruff check是否没有错误，文档生成技能验证输出文件是否存在。

设计验证逻辑的时候要注意两点：

一是验证命令要快。如果每次技能执行后都要跑一遍完整的集成测试，那开发体验会很差。我通常只跑和目标技能直接相关的验证命令，比如只跑新生成的测试文件，而不是整个测试套件。

二是验证失败要有明确的错误信息。不要只返回“验证失败”，要返回具体的失败原因。比如pytest的输出里包含了哪个测试用例失败、失败原因是什么。这些信息会帮助 agent 在回退策略里做出正确的决策。

4. 实操过程与核心环节实现：从零搭建一套技能体系

4.1 环境准备与 skills CLI 安装

假设你已经在使用 Claude Code 或其他支持技能加载的 AI coding agent，接下来需要安装skills CLI。由于这个工具还在快速迭代中，安装方式可能随版本变化，以下是我在 Ubuntu 和 macOS 上都验证过的通用流程。

首先确认 Node.js 环境。skills CLI目前主要通过 npm 分发，需要 Node.js 18 以上版本：

node --version # 如果低于 18，建议用 nvm 升级 nvm install 20 nvm use 20

然后全局安装 CLI：

npm install -g @agent-skills/cli

安装完成后验证：

skills --version

如果提示命令不存在，检查 npm 全局 bin 目录是否在 PATH 里。在 macOS 上通常是/usr/local/bin或~/.npm-global/bin，在 Ubuntu 上通常是/usr/local/bin。可以用npm config get prefix查看实际路径。

注意：如果你在公司内网环境，npm 可能需要配置镜像源。但不要使用任何非官方的代理工具，直接配置 npm 的 registry 即可。

4.2 初始化项目技能目录

进入你的项目根目录，执行初始化命令：

cd /path/to/your/project skills init

这个命令会创建.skills目录和一个默认的skills.yaml配置文件。目录结构大致如下：

.skills/ ├── skills.yaml # 全局配置 ├── test-driven-development/ │ └── skill.yaml # 测试驱动开发技能 ├── code-review/ │ └── skill.yaml # 代码审查技能 └── api-docs/ └── skill.yaml # API 文档生成技能

skills.yaml里可以配置全局选项，比如技能加载的优先级、是否启用自动验证、日志级别等。我的配置通常是这样的：

version: 1 auto_load: true validation: enabled: true timeout: 30 logging: level: info file: .skills/skills.log

auto_load: true表示 agent 会根据触发条件自动加载技能，不需要手动指定。validation.timeout是验证命令的超时时间，单位是秒。超过这个时间还没结束，就认为验证失败。

4.3 编写第一个技能：test-driven-development

test-driven-development是最适合作为入门的技能，因为它的输入输出很明确，验证逻辑也很清晰。

在.skills/test-driven-development/skill.yaml里写入：

name: test-driven-development version: 1.0.0 description: 按照 TDD 流程为指定函数生成测试并验证 triggers: - pattern: "TDD|测试驱动|先写测试" - file_types: [".py", ".js", ".ts"] dependencies: - pytest>=7.0 # Python 项目 - jest>=29.0 # JavaScript 项目 instructions: | 你是一个 TDD 助手，按照以下流程工作： 1. 读取用户指定的函数或模块 2. 先写一个会失败的测试（红） 3. 写最少的代码让测试通过（绿） 4. 重构代码，保持测试通过（重构） 约束： - 测试文件命名：test_<module>.py 或 <module>.test.js - 每个函数至少 3 个测试用例：正常值、边界值、异常值 - 使用项目已有的测试框架，不要引入新依赖 - 断言要具体，不要用 assertTrue(result) 这种模糊断言 示例： 输入：def divide(a, b): return a / b 输出测试： def test_divide_normal(): assert divide(10, 2) == 5 def test_divide_by_zero(): with pytest.raises(ZeroDivisionError): divide(1, 0) def test_divide_negative(): assert divide(-10, 2) == -5 validation: - command: "pytest {test_file} -q" expect_exit_code: 0 timeout: 60 fallback: - action: retry max_attempts: 2 message: "测试未通过，检查函数实现是否正确" - action: report message: "TDD 流程失败，请手动检查"

这个技能定义里，instructions部分用了分步骤的写法，每一步都有明确的动作。validation部分用pytest验证测试是否通过。fallback部分定义了失败后的重试和报告策略。

4.4 在 Claude Code 中加载和使用技能

技能定义写好后，需要在 Claude Code 里加载。如果你用的是 Claude Code 的终端版本，可以在项目根目录下启动：

claude

然后在会话里输入：

/skills load test-driven-development

如果auto_load是开启的，你也可以直接说“帮我为这个函数写测试”，agent 会根据触发条件自动加载技能。

我实测下来，自动加载的准确率在 85% 左右。偶尔会有该加载没加载、或者不该加载却加载了的情况。这时候可以手动用/skills load和/skills unload命令调整。

加载技能后，agent 的行为会有明显变化。它会按照技能定义里的步骤工作，而不是自由发挥。比如我让它为一个calculate_discount函数写测试，它会先输出测试文件，然后运行pytest，根据结果决定是否重试。整个过程比我手动写测试快了大约 3 倍，而且生成的测试用例覆盖度更稳定。

4.5 技能的组合与优先级管理

实际项目中，一个任务往往需要多个技能配合。比如“为新增的 API 接口写测试并生成文档”这个任务，需要test-driven-development和api-docs两个技能。

skills CLI支持技能组合，可以在skills.yaml里定义组合规则：

combinations: - name: api-development skills: - test-driven-development - api-docs priority: 10

当 agent 检测到任务涉及 API 开发时，会同时加载这两个技能。优先级高的组合会覆盖优先级低的，避免技能冲突。

技能冲突是实际使用中比较头疼的问题。比如两个技能都要求“使用 assert 断言”，但一个要求用assert，另一个要求用self.assertEqual。这时候需要明确优先级，或者在技能定义里加上conflicts_with字段，声明这个技能和哪些技能不兼容。

我的经验是，技能数量控制在 10 个以内。超过 10 个之后，触发条件的交叉和冲突会变得难以管理。如果确实需要更多技能，可以考虑分层：基础技能（如代码风格、测试规范）始终加载，领域技能（如特定框架的使用）按需加载。

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

5.1 技能不生效的排查路径

技能不生效是最常见的问题。我整理了一个排查清单，按顺序检查：

我遇到最多的问题是 YAML 缩进错误。YAML 对缩进非常敏感，一个空格不对就会导致解析失败。建议用支持 YAML 语法高亮的编辑器，并且在提交前跑一遍skills validate。

另一个常见问题是触发条件写得太窄。比如只写了pattern: "生成pytest测试"，但用户实际说的是“写单元测试”，结果技能没加载。解决方法是多写几个同义词模式，或者用更通用的模式加上文件类型限制。

5.2 验证失败的典型原因

验证失败通常有三类原因：

第一类是技能指令本身有问题。比如指令里要求“使用 mock 模拟外部调用”，但没有说明 mock 的路径和返回值，agent 生成的代码自然无法通过验证。这时候需要回到技能定义，补充更具体的指令。

第二类是项目环境问题。比如pytest没有安装、Python 版本不对、依赖包缺失。这类问题比较好排查，看验证命令的输出就能定位。

第三类是 agent 执行偏差。有时候 agent 理解了指令，但执行时跑偏了。比如要求“为每个参数生成边界值测试”，它只生成了正常值测试。这时候可以在fallback里加上重试策略，让 agent 再试一次。如果重试后还是不行，就需要人工介入，检查指令是否足够明确。

我踩过的一个坑是验证命令写得太严格。比如要求pytest的退出码必须是 0，但有些测试框架在警告时也会返回非零退出码。后来改成检查输出里是否包含passed关键字，兼容性就好了很多。

5.3 技能版本管理与团队协作

技能是团队资产，需要版本管理。我的做法是把.skills目录纳入 Git 仓库，和代码一起提交。每次修改技能定义，都写清楚变更原因和影响范围。

版本号遵循语义化版本规范：主版本号.次版本号.修订号。指令有重大变更时升主版本号，新增触发条件或验证逻辑时升次版本号，修正错别字或格式时升修订号。

团队协作时，不同成员可能对同一个技能有不同的修改需求。我的建议是，技能定义也要走代码审查流程。修改技能定义后，提交 Pull Request，让其他成员 review。review 的重点是指令是否清晰、验证是否充分、回退策略是否合理。

另外，技能定义里可以加上author和last_updated字段，方便追溯。如果某个技能长期没人维护，可以考虑归档或删除，避免积累技术债务。

5.4 性能优化：减少技能加载的 token 消耗

技能定义会占用 agent 的上下文窗口。如果加载了太多技能，留给实际任务的 token 就少了。我做过一个粗略统计，一个中等复杂度的技能定义大约占用 500 到 1000 个 token。加载 5 个技能就是 2500 到 5000 个 token，对于上下文窗口有限的模型来说，这个开销不小。

优化方法有几个：

一是按需加载。不要一次性加载所有技能，而是根据当前任务动态加载。auto_load机制就是做这个的。

二是精简指令。指令里不要写废话，每个字都要有信息量。能用列表就不用段落，能用示例就不用描述。

三是拆分技能。一个大技能拆成几个小技能，按需组合。比如把“Python 测试”拆成“pytest 基础”、“mock 使用”、“参数化测试”三个技能，用到哪个加载哪个。

四是定期清理。不再使用的技能及时删除或归档，不要让它们占用加载列表。

我目前的项目里常驻加载的技能控制在 3 个以内，其他技能都是按需加载。这样上下文窗口的利用率比较高，agent 的响应速度也更快。

5.5 与其他 AI coding agent 的兼容性

agent-skills目前对 Claude Code 的支持最好，因为 Claude Code 提供了技能加载的接口。其他工具如 Cursor、Copilot、Windsurf 等，支持程度不一。

如果你用的是 Cursor，可以通过.cursorrules文件间接实现类似效果。把技能定义里的instructions部分提取出来，放到.cursorrules里。但这种方式不支持动态加载和验证，灵活性差一些。

如果你用的是开源的 AI coding agent，比如基于 LangChain 或 AutoGPT 搭建的，可以自己写一个技能加载器。核心逻辑就是读取.skills目录，根据触发条件决定加载哪些技能，然后把技能指令注入到 agent 的 system prompt 里。

兼容性问题的本质是，不同 agent 对“技能”这个概念的支持程度不同。agent-skills定义了一套标准，但标准能不能落地，取决于 agent 愿不愿意适配。我的建议是，如果你重度依赖某个 agent，优先选择它原生支持的技能格式；如果你需要跨 agent 使用，agent-skills是一个不错的中间层。

6. 技能体系的扩展方向与个人实践体会

agent-skills这套东西目前还在早期阶段，但它的扩展空间很大。我目前正在尝试的几个方向包括：把技能和 CI/CD 流水线结合，让 agent 在提交代码前自动运行相关技能；把技能和代码审查结合，让 agent 在 review 时自动检查团队规范；把技能和文档生成结合，让 API 文档随代码自动更新。

我个人在实际操作中的体会是，技能体系的价值不在于让 AI 更聪明，而在于让 AI 更一致。模型本身的能力已经很强了，但它每次的表现会有波动。技能的作用是把这种波动收敛到一个可接受的范围内，让输出符合团队的标准和习惯。

最后分享一个小技巧：如果你不确定一个技能该怎么写，可以先手动做一遍任务，把每一步的操作和判断记录下来，然后把这些记录整理成技能定义。这种“先手动、后自动化”的方式，比直接凭空写技能定义要靠谱得多。我最早写的几个技能都是这么来的，一次通过率明显更高。