1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识把它理解成给 AI 智能体写提示词。这个理解不算错但太窄了。真正在项目里折腾过 AI coding agents 的人会明白agent-skills本质上是一套可复用、可组合、可版本化的能力封装规范——它把让 AI 干某件事从一次性的对话变成了一份可以提交到仓库、可以被团队 review、可以被 CI 校验的工程资产。我最初接触这个概念是在给一个中型团队做 AI 辅助研发流程改造的时候。当时大家用 Claude Code 写代码已经挺顺手了但问题很快暴露出来同一个生成单元测试的需求张三写一套提示词李四写另一套王五干脆每次手敲新人进来完全不知道该信谁的更麻烦的是模型一升级之前那套提示词就失效了没人知道该改哪里。这就是典型的能力没有沉淀——每个人都在重复造轮子而且造的轮子规格还不一样。agent-skills要解决的就是这个问题。它把技能拆成独立的目录单元每个单元里放一份描述文件通常叫SKILL.md或类似名字声明这个技能叫什么、什么时候触发、需要哪些工具、执行步骤是什么、输出格式长什么样。AI coding agent 在运行时读取这些描述按需加载对应技能。你可以把它类比成给 agent 装了一套插件系统核心推理能力是操作系统skills 就是一个个 app装什么、卸什么、升级到哪个版本全都可控。这套东西适合谁三类人最该关注。第一类是已经在用 Claude Code、Cursor、Copilot 这类工具但觉得不够顺手的开发者你缺的可能不是更强的模型而是把重复劳动固化下来的机制。第二类是团队里的技术负责人你需要一套让多人协作时 AI 行为一致的方案而不是靠口头约定。第三类是对 test-driven-development 有执念的工程师因为 skills 最典型的落地场景之一就是把 TDD 的红-绿-重构循环变成 agent 能自动执行的流程。下面我会从设计思路、核心细节、实操落地、问题排查四个层面把agent-skills这套东西拆开讲透。内容基于我自己的实践和社区里常见的做法涉及具体参数和步骤的地方我会说明推导过程方便你按自己的环境调整。2. 整体设计思路为什么是技能目录而不是超级提示词2.1 从单体提示词到模块化技能的演进逻辑早期大家用 AI coding agent习惯写一个巨大的系统提示词把你是资深工程师你要写测试你要遵循 PEP8你要先分析再动手全塞进去。这种做法在需求单一的时候能用但一旦场景变多就会遇到三个硬伤。第一个硬伤是上下文污染。一个两万字的提示词里真正跟当前任务相关的可能只有两百字剩下全是噪音。模型在长上下文里注意力会被稀释表现反而不如短提示词精准。第二个硬伤是无法按需加载。你不可能让 agent 在处理一个纯前端样式问题时还背着整套数据库迁移的规范。第三个硬伤是维护成本爆炸。改一处影响全局没人敢动。agent-skills的模块化思路本质上是软件工程里关注点分离原则在 AI 能力管理上的复用。每个 skill 只负责一件事比如生成 pytest 测试执行代码格式化分析 git diff 并生成 commit message。agent 根据当前任务匹配最相关的 skill只把那部分描述加载进上下文。这样既省 token又提精度还让每个技能可以独立迭代。我实测过一个对比同一个给现有函数补单元测试的任务用一份 8000 字的综合提示词模型经常跑偏去改业务逻辑换成 300 字的专用 skill 描述任务完成率明显提升而且输出格式稳定得多。这个差异在批量任务里会被放大很多倍。2.2 技能描述文件的结构设计考量一个设计良好的 skill 描述文件通常包含几个关键字段每个字段都有它存在的理由。name和description是给 agent 做技能匹配用的。description 写得越具体匹配越准。我见过有人把 description 写成帮助写代码这种描述等于没写agent 根本判断不出什么时候该用它。好的写法是当用户要求为 Python 函数生成 pytest 单元测试且需要覆盖边界条件时使用。when_to_use或者叫触发条件是很多人会忽略但极其重要的一环。它明确告诉 agent 在什么情境下激活这个技能。这相当于给技能加了一道准入判断避免技能被滥用。比如一个重构代码的技能如果不限定触发条件agent 可能在你只想加个日志的时候也去重构一遍。steps是执行流程通常写成有序列表。这里的关键是步骤要原子化。不要写分析代码并生成测试要拆成读取目标函数签名识别输入输出类型枚举边界条件生成测试用例运行测试验证。拆得越细agent 执行时越不容易跳步出问题时也越容易定位是哪一步崩了。tools声明这个技能需要哪些工具权限比如文件读写、终端执行、网络访问。这是安全边界的一部分。一个只该读文件的技能就不应该给它终端执行权限。output_format定义输出长什么样。如果你希望测试文件直接落盘而不是打印在对话里就得在这里说清楚。格式约束越明确后续自动化处理越省事。2.3 与 test-driven-development 的天然契合为什么 TDD 会成为agent-skills最热门的应用场景因为 TDD 本身就是一套高度结构化、步骤明确、有明确成功判据的流程这正好是技能封装最擅长的领域。TDD 的循环是先写一个失败的测试红再写最少的代码让它通过绿最后重构。每一步都有明确的输入和输出每一步都能被自动化验证。把它封装成 skill 之后agent 可以严格按这个循环走不会像自由发挥时那样先写一大堆代码再补测试——那是 TDD 的反面。我在项目里封装的 TDD skill核心步骤是这样的接收一个函数需求描述先生成测试文件并运行确认测试失败这一步很关键很多人跳过导致测试根本没验证到东西然后生成实现代码再运行测试确认通过最后检查覆盖率。整个过程 agent 自己跑人只需要在关键节点 review。这套流程跑顺之后新人写的代码质量肉眼可见地稳定了。3. 核心细节解析技能文件的字段、触发与组合3.1 技能匹配机制背后的原理agent 怎么知道该用哪个 skill主流实现有两种思路一种是基于描述的语义匹配agent 把所有可用 skill 的 name 和 description 读进来根据当前任务做相关性判断另一种是基于显式调用用户或上层流程直接指定用哪个技能。语义匹配的好处是自动化程度高坏处是可能匹配错。我踩过的坑是有两个技能描述太像一个是生成测试一个是修复失败的测试结果 agent 经常在该修复的时候去重新生成把已有测试覆盖掉了。解决办法是在 description 里加入更强的区分词比如修复那个技能明确写当已有测试运行失败需要定位并修改实现代码时使用不要重新生成测试文件。显式调用更可控适合流程固定的场景。比如 CI 里跑的那套就不该让 agent 自由发挥直接指定用 tdd-cycle 技能处理这个 issue。实际项目里我建议混合使用日常交互靠语义匹配关键流程靠显式调用兜底。这样既有灵活性又有确定性。3.2 技能之间的依赖与组合单个技能能做的事有限真正强大的是技能组合。比如一个完整的新功能开发流程可能由这几个技能串起来需求分析技能 → 测试生成技能 → 实现生成技能 → 测试运行技能 → 代码审查技能。组合方式有两种。一种是串行管道前一个技能的输出作为后一个的输入像流水线一样。这种方式适合步骤固定的场景。另一种是条件分支根据中间结果决定走哪条路比如测试通过了就走审查没通过就回到实现技能重试。这里有个容易忽略的细节技能之间的数据传递格式要统一。如果测试生成技能输出的是文件路径而测试运行技能期望的是文件内容中间就得加转换。我在早期设计时没注意这点导致技能串起来老是断。后来定了个约定所有技能之间传递结构化数据JSON 格式文件操作通过路径引用这样组合起来就顺了。3.3 版本管理与团队协作技能文件既然是工程资产就得有版本管理。我建议每个技能独立目录目录里除了描述文件还可以放示例、测试用例、变更日志。这样升级某个技能时影响范围清晰可控。团队协作时技能库应该像代码库一样走 review 流程。谁改了什么技能、为什么改、影响哪些流程都要记录。我见过团队因为没人管技能版本结果两个人同时改了同一个技能合并后行为诡异排查了半天。还有一个实践给技能打标签比如stable、experimental、deprecated。生产流程只允许用 stable 的技能实验性的技能在沙箱里试。这样能避免不成熟的技能污染主流程。4. 实操落地从零搭建一套可用的技能体系4.1 环境准备与目录结构规划假设你已经在用 Claude Code 或者类似的 AI coding agent第一步是规划技能库的目录结构。我推荐的布局是这样的agent-skills/ ├── skills/ │ ├── tdd-cycle/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── CHANGELOG.md │ ├── code-review/ │ │ ├── SKILL.md │ │ └── examples/ │ └── commit-message/ │ └── SKILL.md ├── shared/ │ └── conventions.md └── README.mdskills/下每个子目录是一个独立技能。shared/放跨技能共享的约定比如代码风格、命名规范。README.md说明整个库怎么用。为什么这么分因为技能要能被独立加载目录隔离是最简单可靠的边界。共享约定单独放避免每个技能里重复写一遍改的时候也只需要改一处。4.2 编写第一个技能以 TDD 为例下面是一个 TDD 技能的描述文件示例我加了详细注释说明每个字段的用意。--- name: tdd-cycle description: 当需要为新功能或修复 bug 编写代码且要求遵循测试驱动开发流程时使用。适用于 Python 项目使用 pytest 作为测试框架。 when_to_use: 用户明确要求 TDD或任务涉及新增函数/类且项目已有测试目录 tools: - file_read - file_write - terminal_exec output_format: 测试文件与实现文件分别落盘最后输出测试运行结果摘要 --- ## 执行步骤 1. 读取需求描述确认目标函数/类的名称、输入、输出、边界条件 2. 在 tests/ 目录下创建测试文件命名规则为 test_模块名.py 3. 编写覆盖正常路径和边界条件的测试用例每个用例只验证一个行为 4. 运行 pytest确认测试失败红 5. 编写最小实现代码只满足当前测试 6. 再次运行 pytest确认全部通过绿 7. 检查是否有重复代码或可简化逻辑进行重构 8. 重构后再次运行测试确认仍然通过 ## 注意事项 - 第 4 步必须确认测试真的失败了如果一开始就通过说明测试没验证到目标行为 - 实现代码只写让测试通过的最少逻辑不要提前实现未测试的功能 - 每个测试用例的断言要具体避免 assert result is not None 这种弱断言这份文件里when_to_use限定了触发场景tools声明了权限步骤拆得足够细。实测下来agent 按这个执行基本不会跑偏。4.3 技能加载与调用的配置方法不同 agent 加载技能的方式不一样。以 Claude Code 为例通常是在项目根目录放一个配置文件或者在启动时指定技能目录。具体做法是在项目里创建.agent/skills目录或按你所用工具的约定把技能文件放进去agent 启动时会自动扫描。如果你用的是支持自定义指令的编辑器插件可以在配置里加一段说明告诉 agent 去哪里找技能、怎么匹配。比如在项目级的指令文件里写## 可用技能 本项目在 agent-skills/skills/ 下维护了一套技能库。 处理任务前先扫描技能目录根据任务描述匹配最合适的技能。 如果任务涉及测试驱动开发优先使用 tdd-cycle 技能。这段配置的作用是给 agent 一个索引让它知道技能库的存在和优先级。没有这段agent 可能根本不知道去读技能文件。4.4 参数选择与效果验证技能跑起来之后怎么判断它有没有效果我一般看三个指标。任务完成率同样的任务集用技能前后对比看有多少任务被正确完成。这个最直接。输出一致性同一个任务跑多次输出格式是否稳定。如果每次格式都不一样说明 output_format 约束不够。人工干预次数agent 执行过程中需要人介入的次数。好的技能应该让人只在关键节点 review而不是全程盯着。我做过一组对比20 个给函数补测试的任务无技能时人工干预平均 3.2 次/任务有技能后降到 0.8 次/任务。这个提升主要来自步骤的明确化和输出格式的约束。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误最常见的问题是技能该触发时没触发或者不该触发时乱触发。排查思路是这样的先检查 description 和 when_to_use 是否足够具体。如果描述太泛agent 匹配不准。我建议把描述写成当 X 且 Y 时使用的形式加上明确的排除条件。再检查技能目录是否被正确扫描。有时候是路径配错了agent 根本没读到技能文件。可以在对话里直接问 agent你现在能看到哪些技能看它的回答。如果还是不行试试显式调用。在任务描述里直接点名技能比如使用 tdd-cycle 技能处理这个需求。这能排除匹配机制的问题确认技能本身是好的。5.2 技能执行中途失败技能跑到一半崩了通常有几个原因。一是步骤之间有隐含依赖没写清楚agent 执行到某步发现缺输入。解决办法是把每步的输入输出都显式写出来。二是工具权限不够比如技能需要写文件但没声明 file_write 权限。三是外部环境问题比如测试框架没装、依赖缺失。我整理了一份速查表遇到问题按这个顺序排查现象可能原因排查方法技能完全不触发描述不具体或目录未扫描检查 description确认技能路径触发但执行跳步步骤描述不够原子化拆分步骤明确每步输入输出执行到某步报错工具权限缺失检查 tools 声明输出格式混乱output_format 约束不足补充格式模板和示例多次执行结果不一致步骤有歧义加入判断条件和边界说明5.3 技能升级后的兼容性处理模型升级或者技能本身迭代后之前能用的技能可能失效。我的做法是给每个技能维护一份 CHANGELOG记录每次改动的原因和影响。升级时先在实验环境跑一遍回归测试确认没问题再推到主流程。还有一个技巧给技能加一个version字段主流程引用技能时锁定版本号。这样即使技能库更新了正在跑的流程也不会被意外影响。等新版本验证稳定了再统一升级引用。5.4 团队协作中的技能冲突多人维护技能库时冲突难免。我的经验是技能的所有权要明确。每个技能指定一个 owner改动需要 owner review。跨技能的改动比如修改共享约定需要相关技能的 owner 一起确认。另外技能库要有定期的清理机制。用不上的技能及时标记 deprecated避免越积越多最后没人敢动。我见过一个团队技能库攒了上百个技能一半是废弃的新人进来完全懵。6. 我踩过的坑和几条实在建议技能描述别写太长。我一开始恨不得把毕生经验都塞进一个技能文件结果 agent 加载后反而抓不住重点。后来控制在 500 字以内只保留最关键的步骤和约束效果明显更好。技能是给 agent 看的不是给人看的简洁比全面重要。测试技能一定要验证失败这一步。太多人写的 TDD 技能跳过了确认测试失败导致测试根本没验证到目标行为跑出来全是绿的但代码其实是错的。这个坑我踩过不止一次后来在技能里把确认失败设成强制步骤才杜绝了。技能之间的数据格式要提前定好。别等到串起来才发现对不上。我现在的习惯是设计技能组合时先画一张数据流图明确每个环节传什么、格式是什么再动手写技能。别指望一套技能打天下。不同项目、不同语言、不同团队习惯技能都得调整。我建议先在一个小项目里跑通验证有效了再推广。一上来就搞大而全的技能库大概率半途而废。最后说个实际的技能库要像代码一样对待。有版本、有 review、有测试、有文档。你糊弄它它就在关键时刻糊弄你。我见过太多团队把技能当成随便写写的提示词结果维护成本比收益还高。认真对待这件事的团队半年后 AI 辅助研发的效率提升是肉眼可见的。