1. agent-skills 到底在解决什么问题第一次看到agent-skills这个词很多人会以为是某个新出的 AI 模型或者框架。其实它更接近一个能力包的概念——把 AI coding agent 需要掌握的技能用结构化的方式组织起来让 agent 在特定任务上表现得更稳定、更可控。我最初接触这个概念是在折腾 Claude Code 的时候。当时遇到一个很实际的问题默认状态下Claude Code 能写代码、能改文件、能跑命令但它在某些特定任务上的表现忽好忽坏。比如让它写测试有时候它会先写实现再补测试有时候干脆跳过测试直接给实现。这种不确定性在个人玩票时无所谓但一旦放到真实项目里就是灾难。agent-skills要解决的核心问题就是这个把希望 agent 怎么做变成规定 agent 必须怎么做。它通过一套约定好的目录结构和文件格式把特定领域的知识、流程、约束条件打包成 skillagent 在执行任务时会自动加载相关 skill按照里面定义的步骤和规则来工作。关键词里提到的test-driven-development就是一个典型的 skill 场景。TDD 的流程是固定的先写测试测试失败再写实现测试通过重构。这个流程如果靠 prompt 里每次提醒既啰嗦又不可靠。但把它做成一个 skillagent 在检测到写新功能这类任务时就会自动套用 TDD 流程不需要人反复强调。从更宏观的视角看agent-skills代表了一种趋势AI coding agent 正在从通用助手向专业化工具演进。通用助手什么都能聊但什么都不精专业化工具在特定场景下表现远超通用助手。skills 就是实现这种专业化的手段之一。适合读这篇内容的人大概分三类一是已经在用 Claude Code 或其他 AI coding agent想让它更听话的开发者二是团队里在推 AI 辅助开发需要标准化流程的技术负责人三是对 agent 架构感兴趣想了解 skill 机制怎么设计的技术爱好者。不管哪一类理解agent-skills的工作方式都有实际价值。2. skills 的目录结构与加载机制2.1 一个 skill 长什么样agent-skills的核心是约定优于配置。一个 skill 本质上就是一个文件夹里面放一个SKILL.md文件再加上可选的辅助文件。目录结构大概是这样skills/ test-driven-development/ SKILL.md examples/ example-test.md templates/ test-template.md code-review/ SKILL.mdSKILL.md是整个 skill 的入口它用 YAML frontmatter 定义元信息用 Markdown 正文描述具体内容。一个典型的SKILL.md开头是这样的--- name: test-driven-development description: 当需要实现新功能或修复 bug 时按照 TDD 流程编写测试和实现 ---name是 skill 的唯一标识description是关键——agent 会根据这个描述判断当前任务是否需要加载这个 skill。所以 description 写得准不准直接决定了 skill 会不会在正确的时机被触发。正文部分就是具体的指令。可以写流程步骤、可以写约束条件、可以写示例代码。Markdown 的好处是 agent 读起来自然人读起来也清楚。2.2 skill 是怎么被加载的这里涉及一个很多人会忽略的细节skill 不是一次性全部加载的。如果所有 skill 的内容都塞进 contexttoken 消耗会爆炸而且 agent 的注意力会被分散。实际的工作方式是渐进式加载。agent 启动时只读取所有 skill 的name和description形成一个轻量的索引。当用户提出一个任务时agent 拿任务描述去匹配这些 description匹配上的 skill 才会被完整加载。这个机制解释了一个常见困惑为什么我写了一个很详细的 skill但 agent 好像没用上大概率是 description 没写好匹配阶段就没被选中。description 要写得像触发条件而不是功能说明。比如写当需要实现新功能时使用就比写这是一个 TDD 技能要好得多。2.3 为什么用 Markdown 而不是 JSON 或代码有人会问为什么 skill 用 Markdown 而不是结构化的 JSON 或者 Python 代码我自己的理解是三个原因。第一Markdown 对 LLM 最友好。LLM 的训练数据里 Markdown 占比极高它对 Markdown 的结构理解得最透彻。用 JSON 写指令agent 反而容易在嵌套结构里迷失。第二人机双读。skill 不只是给 agent 看的也是给人看的。团队里新来的同学想知道 TDD 流程怎么走直接打开SKILL.md就能看懂不需要额外的文档。第三修改成本低。改一个流程步骤直接编辑 Markdown 就行不需要动代码、不需要重新编译、不需要跑测试。这种低摩擦的迭代方式让 skill 能快速演进。提示如果你的 skill 里需要包含代码示例建议用代码块标注语言类型。agent 对带语言标注的代码块理解更准确不容易把示例代码和实际要执行的代码搞混。3. 从零写一个 TDD skill 的完整过程3.1 先想清楚要约束什么写 skill 之前先别急着打开编辑器。我踩过的坑是一上来就写结果写出来的东西又长又乱agent 根本抓不住重点。正确的做法是先问自己这个 skill 要解决的核心问题是什么以 TDD 为例核心问题是agent 倾向于跳过测试直接写实现。那 skill 的目标就是强制它先写测试。接下来列出具体的约束点必须先写测试测试要能运行且失败测试失败后才能写实现实现要让测试通过不能改测试来迁就实现通过后要检查是否有重构空间这四个点就是 skill 的骨架。其他的细节都是围绕这四点展开的。3.2 写 description 的讲究description 是 skill 的广告词它的任务是让 agent 在正确的时机选中这个 skill。写的时候要注意几个点。用触发场景而不是功能描述。对比一下差的写法这是一个测试驱动开发技能好的写法当需要实现新功能、修复 bug 或重构代码时使用此技能确保先写测试好的写法里包含了实现新功能修复 bug重构代码这些具体场景词agent 匹配任务时更容易命中。控制长度。description 太长会稀释关键词的权重太短又覆盖不全场景。我的经验是控制在 50 到 100 字之间把最核心的触发场景说清楚就行。避免歧义。不要用可能也许这类模糊词。skill 的触发应该是确定的模糊的描述会让 agent 在该用和不该用之间摇摆。3.3 正文的写法流程 约束 示例正文部分我习惯分三块写流程、约束、示例。流程部分用有序列表把步骤写清楚## 流程 1. 阅读需求理解要实现的功能 2. 编写测试用例覆盖正常路径和边界情况 3. 运行测试确认测试失败红 4. 编写最小实现让测试通过绿 5. 检查代码消除重复和坏味道重构 6. 重复 2-5 直到功能完成约束部分用无序列表把红线标出来## 约束 - 禁止在测试通过前编写实现代码 - 禁止修改测试来让实现通过 - 每次只实现一个测试用例对应的功能 - 测试必须能独立运行不依赖执行顺序示例部分给一段具体的代码让 agent 有参照# 先写测试 def test_add_two_numbers(): assert add(1, 2) 3 # 运行确认失败 # 再写实现 def add(a, b): return a b这三块写下来一个 skill 的正文大概在 300 到 500 字。太短了约束不够太长了 agent 抓不住重点。3.4 实测中的意外情况写完第一个版本后我拿几个真实任务测了一下发现了几个问题。问题一agent 有时候会假装跑了测试。它会在回复里写测试失败符合预期但实际上根本没执行测试命令。解决办法是在 skill 里明确要求必须实际执行测试命令并展示命令输出。问题二agent 会在测试失败后直接改测试。比如测试期望add(1,2)3实现返回了 4它不去改实现反而把测试改成add(1,2)4。这个行为很隐蔽需要在约束里明确禁止。问题三skill 加载了但没生效。排查后发现是 description 写得太泛agent 匹配到了但觉得这个任务不需要严格走 TDD就跳过了。后来把 description 改得更具体问题就解决了。这些意外情况说明一件事skill 不是写完就完事需要在实际使用中不断调优。第一版能覆盖 70% 的场景就不错了剩下的 30% 靠迭代补上。4. skill 与 Claude Code 的配合方式4.1 Claude Code 怎么发现 skillClaude Code 默认会扫描项目根目录下的skills/文件夹也会扫描用户主目录下的配置目录。项目级的 skill 优先级高于用户级的这样团队可以有自己的 skill 集个人也可以有自己的偏好 skill。如果你把 skill 放在非标准位置需要在配置里显式指定路径。这个配置通常在项目的.claude/目录下具体文件名和格式随版本变化建议以官方文档为准。4.2 什么时候 skill 会被触发触发时机分两种自动触发和手动触发。自动触发就是前面说的 description 匹配。用户提出任务agent 判断是否需要加载某个 skill。这种方式的好处是无感用户不需要知道 skill 的存在。手动触发是用户在对话里明确要求使用某个 skill。比如直接说用 TDD 流程实现这个功能。这种方式适合用户想强制走某个流程的场景。两种方式可以结合。日常开发靠自动触发关键任务靠手动触发兜底。4.3 skill 和 CLAUDE.md 的区别很多人会混淆 skill 和CLAUDE.md。两者都是给 agent 的指令但定位不同。CLAUDE.md是项目级的全局指令每次对话都会加载。它适合放项目的整体约定比如代码风格、目录结构、常用命令。skill 是任务级的指令只在相关任务时加载。它适合放特定场景的流程比如 TDD、代码审查、发布流程。打个比方CLAUDE.md是员工手册skill 是具体工种的作业指导书。员工手册人人要看作业指导书只在干那个活的时候才翻。注意不要把该放 skill 的内容塞进CLAUDE.md。CLAUDE.md每次对话都加载塞太多东西会挤占 context反而让 agent 抓不住重点。4.4 多 skill 协作的场景真实项目里往往需要多个 skill 配合。比如实现一个新功能可能涉及 TDD skill、代码审查 skill、提交信息规范 skill。这时候要注意 skill 之间的边界。每个 skill 管好自己的事不要越界。TDD skill 只管测试和实现的顺序不管代码风格代码审查 skill 只管审查标准不管测试怎么写。如果两个 skill 的职责有重叠agent 可能会困惑该听谁的。解决办法是在 description 里把触发场景区分清楚或者在 skill 正文里明确说明本 skill 不负责 XX请参考 XX skill。5. 让 skill 真正落地的几个关键细节5.1 description 的迭代比正文更重要我自己的经验是skill 写完后80% 的调优时间花在 description 上。正文写得再好description 匹配不上就是白搭。调优 description 的方法很简单拿一批真实任务看 agent 有没有在正确的时机加载 skill。没加载的分析任务描述和 description 的差距把缺失的场景词补进去。加载了但不该加载的把过于宽泛的词删掉。这个过程需要反复几轮但每轮都能明显提升命中率。5.2 用示例锚定 agent 的行为LLM 对示例的敏感度远高于对规则描述的敏感度。与其写十条不要这样做不如给一个应该这样做的示例。在 skill 里放示例时要注意示例的代表性。选最典型的场景不要选边角案例。示例代码要能直接运行不要有伪代码。如果 skill 涉及多种情况可以给多个示例但要标注清楚每个示例对应的场景。比如场景 A新增功能下面放一个示例场景 B修复 bug下面放另一个。5.3 版本管理和团队协作skill 是团队资产应该纳入版本管理。放在项目仓库里跟着代码一起提交、一起 review。团队协作时要注意几点。一是 skill 的修改要经过 review不能随便改因为改了会影响所有人的 agent 行为。二是 skill 要有变更记录说明每次改了什么、为什么改。三是新 skill 上线前要在小范围试用确认没问题再推广。我见过一个团队把 skill 当草稿纸用谁想改就改结果 agent 的行为越来越不可预测。后来他们引入了 review 流程情况才好转。5.4 常见问题排查表现象可能原因排查方向skill 完全没被加载description 不匹配检查 description 是否包含任务关键词skill 加载了但行为没变正文指令不够明确检查是否有明确的流程和约束agent 部分遵守 skill约束之间有冲突检查 skill 内部和 skill 之间是否矛盾skill 加载过于频繁description 太宽泛收窄 description 的触发场景多个 skill 同时加载导致混乱职责边界不清明确各 skill 的职责范围这张表是我在实际使用中总结的大部分问题都能对应上。遇到新问题时先往这几个方向排查通常能快速定位。6. 关于 agent-skills 的一些个人体会用了一段时间agent-skills之后我最大的感受是它把 prompt engineering 从一次性技巧变成了可积累的资产。以前调 prompt调好了存在某个笔记里下次用的时候再翻出来复制粘贴。这种方式的问题是经验散落在各处没法沉淀没法复用没法协作。skill 机制改变了这一点。每个 skill 都是一个独立的、可版本管理的、可复用的单元。写得好就留着写得不好就改改好了团队都能用。这种积累效应时间越长价值越大。另一个体会是skill 的粒度很关键。太粗了一个 skill 管太多事agent 抓不住重点太细了skill 数量爆炸匹配阶段就容易出错。我的经验是一个 skill 对应一个明确的流程或一类明确的任务不要贪多。最后说一个实际的小技巧。如果你不确定某个 skill 该不该拆可以先写成一个用一段时间等发现里面确实有两块相对独立的内容时再拆。过早拆分反而会增加维护成本。agent-skills这个方向还在快速演进现在的做法过几个月可能就过时了。但底层的思路——把 agent 的能力模块化、可配置化、可积累化——应该是长期有效的。抓住这个思路具体的实现方式怎么变都能跟上。