1. 从 agent-skills 说起为什么我们需要给 AI 编程助手装上“技能包”第一次看到agent-skills这个项目名的时候我脑子里蹦出来的第一个念头是这不就是给 AI coding agents 做的一套“外挂技能库”吗后来花了两天时间把它的结构、用法和背后的设计逻辑摸了一遍发现它解决的问题比我想象的要具体得多——它不是在造一个新的 AI 模型而是在给 Claude Code 这类 AI 编程助手定义一套标准化的“技能描述规范”让 agent 知道在什么场景下该调用什么能力、按什么流程执行、产出什么样的结果。说白了agent-skills干的事情有点像给一个刚入职的工程师发一本《岗位操作手册》。手册里写清楚了遇到写测试的任务该走什么流程、遇到重构该注意哪些边界、遇到调试该按什么顺序排查。没有这本手册AI 也能干活但干出来的活质量参差不齐有时候跳步骤有时候自作主张。有了这本手册它的行为就变得可预期、可复现、可审查。这个项目适合谁来研究我梳理了一下至少三类人会从中获益。第一类是已经在用 Claude Code 或者类似 AI coding agents 做日常开发的工程师你想让 agent 的输出更稳定、更符合团队规范agent-skills提供了一套可以直接参考的模板结构。第二类是在做 AI agent 工具链的开发者你需要一套描述“技能”的 schema 设计思路这个项目里的文件组织方式、元数据字段定义、触发条件写法都值得借鉴。第三类是技术团队的负责人你在考虑怎么把 AI 编程助手引入团队工作流agent-skills里关于 test-driven-development 这类技能的定义方式能帮你理清“怎么让 AI 按照团队标准干活”这件事。我在这篇文章里会把这套东西拆开揉碎讲清楚它的核心设计思路是什么、一个 skill 文件到底长什么样、怎么从零写一个自己的 skill、实际跑起来会遇到哪些坑、以及我踩过之后总结出来的几条实用经验。不管你是刚接触 Claude Code 的新手还是已经在折腾 agent 工作流的老手应该都能从里面找到能直接抄作业的部分。2. agent-skills 的核心设计思路拆解2.1 为什么不是“提示词模板”而是“技能定义”很多人第一次接触agent-skills会把它理解成一套提示词模板集合这个理解偏差挺大的。提示词模板的核心是“告诉 AI 说什么”而 skill 的核心是“告诉 AI 在什么条件下、按什么步骤、做什么事、产出什么”。我举个具体的例子来说明这个区别。假设你要让 AI 帮你写单元测试。如果你用提示词模板你可能会写“请为以下函数编写单元测试使用 Jest 框架覆盖边界情况。”AI 收到之后会给你生成测试代码但每次生成的结构可能不一样有的用describe嵌套有的直接平铺有的覆盖了空值有的忘了异常分支。而agent-skills里的 test-driven-development 技能定义的是这样一套东西触发条件是什么比如用户说“写测试”或者代码变更后需要补测试、执行步骤分几步先分析函数签名和依赖、再识别边界条件、再生成测试骨架、再填充断言、最后跑一遍验证、每一步的产出要求是什么测试文件必须包含哪些 section、断言必须覆盖哪些类型、以及失败之后怎么处理如果测试跑不过是修改测试还是标记问题。这个区别带来的实际影响很大。提示词模板是“一次性”的你每次都要重新描述需求skill 是“可复用”的定义一次之后agent 在遇到匹配场景时会自动按照这套流程走。而且 skill 是可以组合的一个复杂的任务可以拆成多个 skill 串联执行每个 skill 负责一个明确的子任务。2.2 文件结构背后的逻辑为什么是 Markdown YAMLagent-skills的技能定义文件用的是 Markdown 加 YAML frontmatter 的格式。我一开始觉得这个选择挺“轻”的后来想明白了这是为了让技能定义既能被机器解析又能被人阅读和编辑。YAML frontmatter 部分放的是结构化元数据比如技能名称、版本、触发关键词、依赖关系、适用场景标签。这些字段是给 agent 的调度系统读的用来判断“当前任务该不该激活这个技能”。Markdown 正文部分放的是自然语言描述的执行流程、注意事项、示例这些是给 AI 模型读的用来理解具体怎么执行。这种“结构化元数据 自然语言指令”的混合模式比纯 JSON 或纯 YAML 定义要灵活得多。纯结构化定义写起来太死板稍微复杂一点的流程描述就会变得非常臃肿纯自然语言又缺少机器可解析的触发条件。Markdown YAML 的组合刚好卡在中间元数据部分机器友好正文部分模型友好。我实测下来这种格式还有一个好处是版本管理和 diff 特别清晰。技能定义文件放在 Git 仓库里每次修改了哪些步骤、调整了哪些触发条件diff 一目了然。团队协作的时候谁改了什么、为什么改通过 commit message 和 diff 就能追溯。2.3 技能触发机制agent 怎么知道该用哪个 skill这是整个设计里我觉得最巧妙的部分。agent-skills不是让 AI 自己去“猜”该用哪个技能而是通过一套明确的触发规则来匹配。触发规则主要分三类。第一类是关键词触发技能定义里会列出一些触发词比如 test-driven-development 这个技能的触发词可能包括“写测试”“补测试”“测试覆盖”“TDD”等。当用户的输入或者当前上下文里出现这些词时调度系统就会把这个技能标记为候选。第二类是场景触发基于当前的工作状态来判断。比如检测到代码文件被修改了但对应的测试文件没有更新就自动触发测试相关的技能。这种触发方式不依赖用户显式说“我要写测试”而是根据上下文推断。第三类是显式调用用户直接说“用 TDD 技能来写这个模块”agent 就会跳过匹配阶段直接加载对应的技能定义。这三类触发方式的优先级和组合逻辑在agent-skills的调度层里有明确的定义。我实际用下来感觉关键词触发和场景触发的组合是最实用的因为大部分时候用户不会显式说“我要用什么技能”而是直接描述任务这时候就需要系统自己判断。2.4 与 Claude Code 的集成方式agent-skills本身是一个独立的技能定义规范但它最常见的落地场景是配合 Claude Code 使用。Claude Code 作为 AI coding agent在执行任务时会读取当前项目下的技能定义文件根据触发规则加载对应的技能然后按照技能描述的流程来执行。集成的关键点在于技能文件的存放位置和加载顺序。我试过几种不同的组织方式最后发现比较合理的是在项目根目录下建一个.agent-skills/目录里面按技能类别分文件夹存放。Claude Code 启动时会扫描这个目录把所有技能定义加载到内存里然后根据当前任务动态匹配。这里有一个细节值得注意技能定义的加载是有优先级的。项目级的技能定义会覆盖全局级的同名技能这意味着你可以在项目里定制一套适合当前代码库的技能而不影响其他项目。这个设计对于团队协作来说很实用因为不同项目的技术栈和规范可能完全不同。3. 一个 skill 文件到底长什么样逐字段拆解3.1 YAML frontmatter 的必填字段与选填字段我拿一个实际的 test-driven-development 技能定义来举例把每个字段的作用和写法讲清楚。先看 frontmatter 部分--- name: test-driven-development version: 1.2.0 description: 按照 TDD 流程为指定代码生成单元测试 trigger_keywords: - 写测试 - 补测试 - TDD - 测试覆盖 trigger_scenarios: - code_changed_without_test - new_function_added dependencies: - code-analysis - test-runner tags: - testing - quality author: team-platform ---name是技能的唯一标识必须用 kebab-case 格式不能有空格和大写字母。这个字段在技能被引用和调用时使用所以一旦定下来就不要随便改否则依赖它的其他技能会断掉。version遵循语义化版本规范主版本号变更表示不兼容的修改次版本号表示新增功能修订号表示修复。我建议每次修改技能定义都更新版本号这样在排查问题时能快速定位是哪个版本的技能导致了异常。description是一句话描述会显示在技能列表和日志里。写的时候要具体不要写“一个测试技能”这种废话要写清楚“按照 TDD 流程为指定代码生成单元测试”让人一眼就知道这个技能干什么。trigger_keywords和trigger_scenarios是触发条件前面已经讲过。这里补充一点关键词不要写得太宽泛比如只写“测试”两个字会导致很多不相关的任务都触发这个技能。我一般会写两到三个字的组合词比如“写测试”“补测试”“测试覆盖”精确度会高很多。dependencies声明这个技能依赖的其他技能。比如 test-driven-development 依赖 code-analysis 来先分析代码结构依赖 test-runner 来执行生成的测试。调度系统在加载这个技能时会先确保依赖的技能已经加载。tags是分类标签用于技能管理和检索。我习惯按“领域 类型”两个维度打标签比如testing是领域quality是类型。3.2 Markdown 正文的结构规范frontmatter 下面的 Markdown 正文我总结了一个比较通用的结构模板包含四个部分概述、前置条件、执行步骤、输出要求。概述部分用两三句话说明这个技能解决什么问题、适用什么场景。不要写太长因为 AI 模型读的时候会把它作为“这个技能是干什么的”的第一印象。前置条件部分列出执行这个技能之前必须满足的条件。比如 test-driven-development 的前置条件可能包括目标代码文件已经存在且可解析、项目里已经配置了测试框架、测试运行命令可用。这些条件会被调度系统检查不满足的话技能不会被激活。执行步骤部分是核心用有序列表描述每一步做什么。每一步要写清楚操作内容、预期产出、如果失败怎么处理。我写的时候会尽量把步骤拆细每一步只做一件事这样 AI 执行的时候不容易跳步或者混淆。输出要求部分定义技能执行完成后应该产出什么。比如测试文件必须包含哪些 section、断言必须覆盖哪些类型、测试运行结果必须包含哪些信息。这部分是质量检查的依据写得越具体产出的一致性越高。3.3 触发条件的写法与优先级触发条件的写法直接决定了技能能不能在正确的时机被激活。我踩过的坑是一开始把触发关键词写得太少导致很多该触发的时候没触发后来又把关键词写得太宽泛导致不该触发的时候乱触发。经过几轮调整我总结了一个比较稳的写法每个技能写三到五个精确关键词再加两到三个场景触发条件。关键词负责“用户明确说了要做什么”的情况场景触发负责“用户没说但上下文表明需要做”的情况。优先级方面显式调用 关键词触发 场景触发。也就是说如果用户直接说了“用 TDD 技能”那就无条件加载如果用户说了“写测试”那就匹配关键词如果用户什么都没说但代码变更了且没有对应测试那就靠场景触发。这里有一个细节多个技能同时被触发时怎么处理。agent-skills的调度层会计算每个技能的匹配分数分数高的优先加载。匹配分数的计算规则包括关键词命中数量、场景匹配程度、技能优先级标签等。我一般会给核心技能打上priority: high标签确保它们在竞争时胜出。3.4 一个完整示例test-driven-development 技能定义把上面的内容串起来一个完整的 test-driven-development 技能定义大概长这样--- name: test-driven-development version: 1.2.0 description: 按照 TDD 流程为指定代码生成单元测试 trigger_keywords: - 写测试 - 补测试 - TDD trigger_scenarios: - code_changed_without_test dependencies: - code-analysis - test-runner tags: - testing - quality priority: high --- ## 概述 为指定的函数或模块生成符合项目规范的单元测试覆盖正常路径、边界条件和异常分支。 ## 前置条件 - 目标代码文件存在且语法正确 - 项目已配置测试框架Jest / Pytest / JUnit 等 - 测试运行命令可用 ## 执行步骤 1. 分析目标函数的签名、参数类型、返回值类型和依赖项 2. 识别所有分支路径包括 if/else、switch、try/catch 3. 为每个分支路径设计至少一个测试用例 4. 生成测试文件骨架包含 describe 块和 it 块 5. 填充断言确保每个测试用例都有明确的期望值 6. 运行测试检查是否全部通过 7. 如果有失败分析是测试问题还是代码问题分别处理 ## 输出要求 - 测试文件命名遵循 *.test.* 或 *_test.* 规范 - 每个公开函数至少有一个对应的 describe 块 - 边界条件测试必须包含空值、极值、类型错误三种情况 - 测试运行结果必须包含通过数、失败数、耗时这个定义我实际用过很多次效果比较稳定。当然具体项目里会根据技术栈调整比如 Python 项目会把 Jest 换成 Pytest断言风格也会不一样。4. 从零写一个自己的 skill完整实操流程4.1 环境准备与目录结构规划在开始写 skill 之前先把目录结构规划好。我试过几种组织方式最后觉得下面这种最清晰project-root/ ├── .agent-skills/ │ ├── testing/ │ │ ├── test-driven-development.md │ │ └── integration-test.md │ ├── refactoring/ │ │ ├── extract-function.md │ │ └── rename-symbol.md │ ├── debugging/ │ │ └── root-cause-analysis.md │ └── _config.yaml ├── src/ └── tests/按技能类别分文件夹每个技能一个 Markdown 文件。_config.yaml放全局配置比如技能加载路径、默认优先级、日志级别等。全局配置的一个示例skill_paths: - .agent-skills default_priority: medium log_level: info auto_reload: trueauto_reload设为 true 时修改技能定义文件后不需要重启 Claude Code下次触发时会自动加载新版本。这个在调试技能定义的时候特别方便。4.2 定义技能元数据名称、版本、触发条件写一个新技能第一步是确定它的边界。我一般会问自己三个问题这个技能解决什么问题什么情况下该用它它依赖什么其他能力拿一个实际例子来说我想写一个“代码审查”技能帮助 AI 在提交代码前做一轮自查。名称定为code-review版本从0.1.0开始因为还没稳定描述写“对变更代码进行静态审查检查命名规范、错误处理、边界条件”。触发条件方面关键词我选了“代码审查”“review”“自查”场景触发选了before_commit和pr_created。依赖项声明了code-analysis和lint-runner。这里有一个经验新技能的版本号从0.1.0开始等实际用过几轮、确认稳定之后再升到1.0.0。不要一上来就写1.0.0因为后面肯定要改版本号跳来跳去反而混乱。4.3 编写执行步骤颗粒度控制与顺序编排执行步骤的颗粒度控制是写 skill 最考验经验的地方。写得太粗AI 执行的时候会自由发挥产出不稳定写得太细又会让 AI 变得死板遇到稍微不同的情况就卡住。我的经验是每个步骤对应一个明确的“动作 产出”。比如“分析目标函数的签名和依赖”是一个步骤产出是函数的基本信息“识别分支路径”是下一个步骤产出是分支列表。每个步骤的产出都是下一步的输入这样串起来形成一条清晰的流水线。顺序编排方面我一般遵循“先分析后执行、先局部后整体、先正常后异常”的原则。先让 AI 理解现状再让它动手改先处理单个函数再处理整个模块先覆盖正常路径再补异常分支。还有一个细节步骤之间如果有依赖关系要显式写出来。比如“步骤 3 必须在步骤 2 完成之后执行”这样 AI 不会跳步。如果步骤之间可以并行也标注出来能提高执行效率。4.4 输出要求与质量校验规则输出要求这部分我建议写得越具体越好。因为这是 AI 判断“我做完了没有”的依据也是你事后检查产出的标准。我一般会从三个维度写输出要求格式要求、内容要求、验证要求。格式要求定义产出的文件类型、命名规范、结构模板。比如“测试文件必须以.test.ts结尾”“必须包含 describe 和 it 块”。内容要求定义必须覆盖的内容点。比如“每个公开函数至少一个测试用例”“边界条件必须包含空值、极值、类型错误”。验证要求定义怎么确认产出是合格的。比如“运行测试命令所有测试必须通过”“lint 检查不能有 error 级别的问题”。这三个维度写清楚之后AI 执行完技能你可以快速对照检查不用逐行读代码。4.5 实际跑一遍用 Claude Code 加载并触发技能技能定义写完之后实际跑一遍验证。我用的流程是这样的第一步把技能文件放到.agent-skills/目录下确保 Claude Code 能扫描到。如果auto_reload开着不用重启否则重启一下 Claude Code。第二步在对话里输入触发关键词比如“帮我给这个函数写测试”。观察 Claude Code 的日志看它有没有加载 test-driven-development 技能。日志里一般会打印“matched skill: test-driven-development”之类的信息。第三步检查执行过程是否符合技能定义的步骤。如果 AI 跳步了说明步骤描述不够明确需要回去改。如果 AI 卡在某一步说明那一步的指令有歧义也要改。第四步检查产出是否符合输出要求。如果不符合对照输出要求逐条排查看是哪条没写清楚。我实测下来一个新技能从写完到稳定一般要改三到五轮。第一轮改触发条件第二轮改步骤颗粒度第三轮改输出要求后面几轮微调。不要指望一次写完美。5. 常见问题与排查技巧实录5.1 技能不触发触发条件排查清单技能不触发是最常见的问题我整理了一个排查清单按顺序检查排查项检查方法常见原因文件位置确认技能文件在.agent-skills/目录下放错目录扫描不到文件格式检查 frontmatter 是否合法 YAML缩进错误、冒号缺失必填字段确认 name、version、description 都存在漏写字段导致解析失败触发关键词检查关键词是否在用户输入中出现关键词写得太偏用户不会这么说场景触发检查场景条件是否满足场景定义太严格实际很难满足优先级检查是否有更高优先级的技能抢占了多个技能竞争低优先级的被忽略依赖项检查依赖的技能是否已加载依赖缺失导致技能被跳过我遇到最多的情况是触发关键词写得太“技术化”比如写了“单元测试覆盖”但用户实际说的是“帮我写个测试”。后来我改成写两到三个不同风格的关键词覆盖正式和口语化的表达触发率就上来了。5.2 技能执行到一半卡住步骤拆解与依赖检查技能执行到一半卡住通常是因为某一步的指令有歧义AI 不确定该怎么继续。排查方法是看日志里最后执行到哪一步然后检查那一步的描述。我遇到过一个典型情况步骤里写了“分析代码结构”但没有说明分析到什么程度算完成。AI 分析了一半不确定要不要继续就卡住了。后来我改成“分析代码结构产出函数列表和依赖关系图”有了明确的产出要求AI 就知道什么时候算完成。另一个常见原因是依赖项没有正确加载。比如 test-driven-development 依赖 test-runner但 test-runner 技能没有定义或者加载失败导致 test-driven-development 执行到“运行测试”这一步时找不到可用的运行器。排查方法是检查依赖链确保每个依赖项都能独立加载。5.3 产出不符合预期输出要求细化与示例补充产出不符合预期大部分时候是输出要求写得太模糊。比如只写了“生成测试代码”没有说清楚测试代码要包含什么、遵循什么规范。我的解决方法是在输出要求里加一个“示例”部分给出一段符合要求的产出样例。AI 看到具体示例之后模仿的准确率会高很多。比如 test-driven-development 的输出要求里我加了一段示例测试代码describe(calculateDiscount, () { it(should return 0 for empty cart, () { expect(calculateDiscount([])).toBe(0); }); it(should throw for negative total, () { expect(() calculateDiscount([{ price: -10 }])).toThrow(); }); });有了这个示例AI 生成的测试代码结构和风格就稳定多了。5.4 多个技能冲突优先级与互斥规则设置多个技能同时被触发时如果没有明确的优先级规则AI 可能会在几个技能之间反复横跳导致执行混乱。我的做法是给每个技能打上priority标签分 high、medium、low 三档。核心技能比如代码分析、测试生成设为 high辅助技能比如格式化、注释生成设为 low。调度系统会优先加载 high 优先级的技能。如果两个技能确实互斥比如“重构”和“快速修复”在某些场景下不能同时用可以在技能定义里加exclusive_with字段声明它和哪些技能互斥。调度系统检测到互斥时会根据优先级选择其中一个。5.5 性能问题技能加载慢、执行超时的优化技能数量多了之后加载和执行可能会变慢。我遇到过加载 50 多个技能时Claude Code 启动明显变慢的情况。优化方法有几个。第一把不常用的技能归档到_archive/目录不参与加载。第二给技能定义文件“瘦身”把大段的示例代码移到单独的examples/目录技能文件里只保留引用。第三开启lazy_load模式技能只在第一次被触发时才加载而不是启动时全部加载。执行超时的问题一般是某个步骤的指令让 AI 做了太多事情。比如“分析整个项目的代码结构”这种指令在大项目上会跑很久。解决方法是把步骤拆细限定每次分析的范围比如“分析当前文件的代码结构”。6. 我踩过的坑与实用经验总结6.1 技能定义不是越详细越好我一开始写技能定义的时候恨不得把每个细节都写进去结果发现 AI 执行的时候反而变得死板遇到稍微不同的情况就不知道变通。后来我调整了策略核心流程写详细边缘情况写原则。比如“分析函数签名”这一步我会写清楚要提取哪些信息参数名、类型、默认值、返回值类型但不会规定用什么方法提取。这样 AI 在遇到不同语言、不同框架时能自己选择合适的方法。6.2 版本管理技能定义的迭代与回滚技能定义文件一定要用 Git 管理而且每次修改都要写清楚 commit message。我吃过亏改了一个触发关键词导致某个技能频繁误触发但忘了改之前是什么回滚的时候找不到正确的版本。现在我养成的习惯是每次修改技能定义commit message 里写清楚“改了什么、为什么改、预期效果是什么”。比如“将 test-driven-development 的触发关键词从‘测试’改为‘写测试’避免与 integration-test 技能冲突”。6.3 团队协作技能定义的评审与共享团队里多个人维护技能定义时需要一套评审机制。我们的做法是技能定义的修改走 Pull Request 流程至少一个人 review 之后才能合并。Review 的重点是触发条件是否合理、步骤描述是否有歧义、输出要求是否可验证。共享方面我们把通用的技能定义放在一个独立的仓库里各个项目通过 Git submodule 或者包管理工具引入。项目特有的技能定义放在项目自己的.agent-skills/目录下覆盖通用版本。6.4 与 test-driven-development 的配合心得test-driven-development 是我用得最多的技能之一配合 Claude Code 使用下来有几个心得值得分享。第一让 AI 先写测试再写实现比先写实现再补测试的效果好很多。因为先写测试的时候AI 会先思考函数的输入输出和边界条件写实现的时候目标更明确。第二测试跑失败的时候不要直接让 AI 改测试来“通过”。要让 AI 分析是测试写错了还是实现有问题分别处理。我在技能定义里专门加了一步“分析失败原因”就是为了防止 AI 走捷径。第三测试覆盖率不是越高越好。我一般让 AI 覆盖正常路径、边界条件、异常分支这三类覆盖率大概在 70% 到 80% 之间就够了。追求 100% 覆盖率会生成很多无意义的测试维护成本反而更高。6.5 后续扩展方向技能组合与自动化流水线agent-skills目前主要解决的是“单个技能怎么定义和触发”的问题后续可以往两个方向扩展。一个是技能组合。把多个技能串成一条流水线比如“代码分析 → 测试生成 → 代码审查 → 提交”每个技能负责一个环节前一个的输出作为后一个的输入。这样可以把复杂的开发流程标准化。另一个是自动化触发。结合 CI/CD 系统在代码提交、合并请求、定时任务等事件发生时自动触发对应的技能。比如每次 push 代码时自动跑一遍代码审查技能发现问题就阻断合并。这两个方向我都在尝试目前技能组合已经跑通了基本流程自动化触发还在调试阶段。等稳定之后再整理一篇经验分享。6.6 一个容易被忽略的细节技能定义的“冷却期”最后分享一个我踩坑之后加上的机制技能冷却期。有些技能触发太频繁会导致 AI 反复执行同一个动作比如代码审查技能在每次文件保存时都触发搞得 AI 一直在审查没法干别的活。我在技能定义里加了一个cooldown字段单位是秒。比如cooldown: 300表示这个技能触发后 5 分钟内不会被再次触发。这个机制对于场景触发的技能特别有用能避免 AI 陷入“触发-执行-再触发”的循环。冷却期的值要根据技能的执行频率来定。高频技能比如格式化可以设短一点60 秒左右低频技能比如架构分析可以设长一点600 秒以上。我一般从 300 秒开始试根据实际触发频率调整。