1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把散落在各个仓库里的提示词、脚本、工作流给收拢到一块儿吗但真正翻完它的结构、跑通几个技能之后我意识到这东西的价值远不止提示词合集这么简单。它本质上是在给 AI coding agents 定义一套可复用、可组合、可测试的能力单元让代理不再每次都从零开始猜你想干什么。如果你最近在折腾 Claude Code、Cursor、或者任何一类能读写文件、执行终端命令的编码代理你大概率遇到过这几个痛点同一个项目里代理每次生成的代码风格飘忽不定让它写测试它给你写一堆断言空壳让它重构它顺手把不相关的模块也改了。这些问题的根源不在于模型不够强而在于你没有给它一套稳定的、约定俗成的技能规范。agent-skills想解决的正是这件事。这篇文章适合三类人看一是刚接触 AI coding agents、还在摸索怎么让代理听话的新手二是已经在团队里用 Claude Code 做日常开发、想把个人经验沉淀成团队资产的中级用户三是想自己写技能、扩展代理能力边界的老手。我会从整体设计思路讲到具体实操把 skills CLI 的用法、test-driven-development 这类核心技能的落地方式、以及我在实际使用中踩过的坑都摊开来说。读完你至少能做到自己写一个能跑通的技能把它接进 Claude Code并且知道怎么验证它到底有没有生效。先给个最朴素的类比。你可以把 AI coding agent 想象成一个刚入职的实习生脑子很聪明但对你们团队的规矩一无所知。agent-skills就是那本《新人上手手册》——里面写清楚了提交代码前必须跑测试改数据库字段要同步改迁移脚本日志格式统一用这个模板。手册写得越细实习生犯的错就越少。区别在于这本手册是给机器看的所以它得是结构化的、可被程序解析的、最好还能自动校验的。2. agent-skills 的整体设计与思路拆解2.1 核心思路把经验变成可加载的模块传统做法里我们让代理遵守规范靠的是在对话里反复叮嘱或者写一个巨大的 system prompt 塞满各种规则。这两种方式都有明显缺陷前者不可复用换个会话就忘了后者臃肿且难以维护规则一多模型反而抓不住重点。agent-skills的解法是分而治之。它把每一类能力拆成一个独立的技能单元每个单元有自己的元数据叫什么、什么时候触发、需要什么工具、指令正文具体怎么做、以及可选的辅助资源脚本、模板、测试用例。代理在运行时根据当前任务动态加载相关技能而不是一次性把所有规则灌进去。这个设计的好处很直接。第一上下文利用率高。你不需要在每次对话里都带上全部规则只在需要时加载对应技能省下来的 token 可以留给真正的业务代码。第二可测试。每个技能可以单独验证写一个测试用例喂给它看输出是否符合预期这比测试一整个巨型 prompt 靠谱得多。第三可组合。一个写测试的技能可以和一个重构的技能串联使用形成工作流。我个人的判断是这套思路借鉴了软件工程里关注点分离和依赖注入的思想只不过注入的对象从代码模块变成了代理的行为规范。理解了这一点后面所有的目录结构、CLI 命令、加载机制都会变得顺理成章。2.2 为什么选择 CLI 作为主要交互方式agent-skills提供了 skills CLI而不是只做一个图形界面或者纯配置文件。这个选择背后有实际考量。CLI 天然适合集成到现有的开发流程里——你可以在 CI 里跑技能校验可以在 git hook 里触发技能更新可以用脚本批量管理几十个技能。图形界面做不到这些或者说做起来很别扭。更重要的是CLI 让技能的分发变得简单。一个技能打包好之后通过一条命令就能安装到本地跟装 npm 包、pip 包的体验是一致的。对于团队协作场景这意味着你可以把技能仓库当成代码仓库来管理走同样的 review、版本、发布流程。提示如果你之前只用过 Claude Code 的对话界面从没碰过命令行别慌。skills CLI 的常用命令就那么几个我在第 3 节会把每个命令的用途和参数都列清楚照着敲一遍就熟了。2.3 与 Claude Code 等代理的集成逻辑agent-skills本身不是一个代理它是一套技能规范加工具链。真正干活的是 Claude Code 这类代理。集成的关键在于技能发现和加载机制代理启动时扫描指定目录读取每个技能的元数据建立索引当用户发起一个任务时代理根据任务描述匹配相关技能把技能内容注入到当前上下文。这里有个容易忽略的细节技能不是越多越好。如果你装了五十个技能代理每次匹配都要遍历一遍不仅慢还可能匹配到不相关的技能导致行为混乱。所以agent-skills在元数据里设计了触发条件字段让匹配更精准。我在实际使用中的经验是单个项目常驻的技能控制在 5 到 10 个比较合适其余的按需临时加载。3. 核心细节解析与实操要点3.1 技能目录结构每个文件都有存在的理由一个标准的技能单元通常长这样my-skill/ ├── skill.json # 元数据名称、描述、触发条件、依赖 ├── instructions.md # 指令正文代理具体要做什么 ├── resources/ # 可选脚本、模板、示例 │ ├── template.py │ └── example.md └── tests/ # 可选验证技能是否生效的测试 └── test_cases.jsonskill.json是整个技能的入口代理先读它。里面最关键的是triggers字段它决定了这个技能什么时候被激活。触发条件可以基于关键词、文件类型、任务类型等多种维度。我见过有人把触发条件写得特别宽泛结果技能到处乱触发反而干扰了正常开发。触发条件要写得像正则表达式一样精确宁可漏触发也不要误触发漏了可以手动调用误了就是灾难。instructions.md是技能的灵魂。写这个文件的时候我建议遵循一个原则把代理当成一个聪明但缺乏上下文的新人。不要写优化代码这种模糊指令要写检查函数是否超过 50 行如果超过提取出独立的子函数并补充单元测试。越具体代理执行得越稳定。3.2 触发条件的设计精准匹配比广撒网更重要触发条件的设计直接决定了技能体系的可用性。我整理了几种常见的触发维度以及各自的适用场景触发维度示例适用场景注意事项关键词匹配任务描述含写测试通用技能关键词要选独特词避免代码修改这类高频词文件类型操作.sql文件时领域技能需确认代理能正确识别文件类型任务类型重构、调试、文档生成工作流技能任务分类本身可能不准需配合人工确认显式调用用户输入/skill-name所有技能最可靠但需要用户记住技能名实际使用中我通常采用组合触发关键词匹配做主触发文件类型做二次过滤。比如一个数据库迁移技能触发条件是任务描述含迁移或migration且当前操作文件是.sql或迁移脚本目录下的文件。这样能大幅降低误触发率。3.3 指令正文的写法从能跑到跑得稳指令正文的写法有很多流派我试过几种之后总结出一套比较稳的模板目标陈述一句话说清楚这个技能要达成什么结果。前置检查执行前需要确认哪些条件比如确认当前目录有 package.json。执行步骤分步骤列出具体操作每步都要可验证。输出格式明确代理应该输出什么是代码、是报告、还是修改后的文件。异常处理遇到什么情况应该停下来问用户而不是自作主张。这个模板看起来啰嗦但它能显著降低代理跑偏的概率。我做过对比测试用模板写的技能首次执行成功率比随手写的技能高出不少。原因很简单代理在执行过程中有明确的检查点不会一条道走到黑。注意指令正文里不要写尽量最好如果可以这类模糊词汇。代理对这类词的理解和人类不一样它可能直接忽略也可能过度解读。要么写必须要么写可选默认不执行。4. 实操过程与核心环节实现4.1 环境准备从零搭好 skills CLI假设你用的是 macOS 或者 Ubuntu先把基础环境准备好。Node.js 版本建议 18 以上因为 skills CLI 依赖的一些包对低版本支持不好。# 检查 Node 版本 node -v # 如果低于 18用 nvm 升级 nvm install 20 nvm use 20 # 全局安装 skills CLI npm install -g agent-skills/cli # 验证安装 skills --version装完之后初始化一个技能工作目录# 创建技能仓库目录 mkdir my-agent-skills cd my-agent-skills # 初始化 skills init # 这会生成一个 skills.json 配置文件和 skills/ 目录skills.json里配置的是技能仓库的元信息比如仓库名、版本、技能存放路径。默认路径是./skills你可以改成任何你习惯的位置。4.2 写第一个技能以 test-driven-development 为例test-driven-development 是热词里出现频率很高的一个技能也是最能体现 agent-skills 价值的场景之一。我拿它当例子完整走一遍从创建到验证的流程。先创建技能骨架skills create test-driven-development这会在skills/下生成一个目录里面已经有skill.json和instructions.md的模板。接下来编辑skill.json{ name: test-driven-development, version: 1.0.0, description: 在实现新功能前先写测试确保代码可验证, triggers: { keywords: [写测试, TDD, 测试驱动, 先写测试], fileTypes: [.py, .js, .ts, .java] }, dependencies: [], resources: [resources/test-template.py] }然后写instructions.md这是核心。我把自己用的版本简化后贴出来## 目标 在实现任何新功能之前先编写对应的测试用例确保功能有明确的验证标准。 ## 前置检查 - 确认项目已有测试框架pytest / jest / junit 等 - 确认测试文件存放位置符合项目约定 ## 执行步骤 1. 阅读用户需求提取出可验证的行为点 2. 为每个行为点编写一个测试用例测试用例必须包含 - 输入数据 - 预期输出 - 断言语句 3. 运行测试确认测试失败因为功能还没实现 4. 实现功能代码直到测试通过 5. 重构代码保持测试通过 ## 输出格式 - 先输出测试文件内容 - 再输出实现代码 - 最后输出测试运行结果 ## 异常处理 - 如果项目没有测试框架停下来询问用户是否安装 - 如果测试无法运行输出错误信息并停止写完这两个文件一个技能就成型了。但成型不等于能用接下来要验证。4.3 技能验证怎么确认它真的生效了agent-skills提供了skills test命令可以跑技能自带的测试用例。但更实用的验证方式是在真实代理里试跑。我通常分三步走第一步本地校验技能格式skills validate test-driven-development这个命令会检查skill.json的字段是否完整、instructions.md是否存在、引用的资源文件是否都能找到。格式错误会在这里暴露出来。第二步模拟触发skills simulate test-driven-development --task 帮我给用户登录功能写测试这个命令会模拟代理的匹配逻辑告诉你这个技能会不会被触发、匹配度多高。如果匹配度低于阈值说明触发条件需要调整。第三步接入 Claude Code 实测。把技能目录链接到 Claude Code 的技能扫描路径skills link test-driven-development --target ~/.claude/skills然后在 Claude Code 里发起一个真实任务观察代理是否加载了技能、执行是否符合预期。这一步最能暴露问题因为真实任务的复杂度远超模拟场景。4.4 参数计算与阈值选择技能匹配涉及一个匹配度阈值默认是 0.7。这个值不是拍脑袋定的背后有个简单的计算逻辑。假设一个技能有 3 个关键词触发条件任务描述命中了 2 个那么基础匹配度是 2/3 ≈ 0.67低于 0.7 就不会触发。如果命中了全部 3 个匹配度是 1.0肯定触发。这个设计意味着关键词不要写太多。写 10 个关键词命中 7 个才算触发实际上很难达到。我的经验是每个技能的关键词控制在 3 到 5 个且这几个词要足够独特。比如写测试就比测试好因为测试可能出现在测试环境测试数据等不相关的语境里。文件类型过滤是二次判断不参与匹配度计算只做硬性过滤。也就是说如果任务涉及的文件类型不在列表里直接不触发不管关键词匹配度多高。这个设计避免了技能在错误场景下被激活。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序建议如下排查项检查方法常见原因技能是否被扫描到skills list目录路径配错、技能未 link元数据是否合法skills validate nameJSON 语法错误、必填字段缺失触发条件是否匹配skills simulate name --task ...关键词太偏、文件类型不匹配匹配度是否达标看 simulate 输出的匹配度数值关键词命中数不足代理是否支持技能加载查代理文档代理版本过低、未开启技能功能我遇到过一次特别隐蔽的情况技能明明配置正确simulate 也显示匹配度 0.9但实际用的时候就是不触发。查了半天发现是技能目录的权限问题代理进程没有读取权限。所以排查的时候别忘了看一眼文件权限。5.2 技能触发了但执行结果不对这种情况通常是instructions.md写得不够明确。代理触发了技能但理解偏了。解决办法是把指令拆得更细每一步都加上验证条件。比如不要写实现功能要写实现功能实现后运行测试如果测试失败则输出失败原因并停止。另一个常见原因是技能之间有冲突。两个技能都对同一类任务有触发条件代理可能同时加载了两个指令互相打架。解决办法是给技能设置优先级或者在触发条件上做互斥设计。5.3 技能加载后代理变慢技能加载会占用上下文窗口加载太多技能确实会拖慢响应速度。我的做法是分层管理常驻技能只保留最核心的 3 到 5 个其余技能放在按需加载目录里通过显式调用触发。这样既保证了常用能力的稳定性又不会让上下文爆炸。还有一个技巧是技能瘦身。instructions.md里不要放太多示例代码示例放到resources/目录里指令正文只引用文件名。代理需要的时候再去读不需要就不占上下文。5.4 团队协作中的技能版本管理多人协作时技能仓库的版本管理是个绕不开的问题。我的建议是技能仓库独立于业务仓库单独走版本发布流程。每个技能有自己的版本号业务项目通过skills.json锁定依赖的技能版本。这样技能升级不会意外影响正在开发的项目需要升级时显式更新版本号即可。提示技能仓库的 commit message 建议遵循语义化版本规范比如feat: 新增数据库迁移技能、fix: 修复测试技能触发条件。这样生成 changelog 的时候省事团队其他人也能快速了解变更内容。5.5 常见问题速查表问题现象可能原因快速解决技能完全不触发未 link 或路径错误重新执行skills link触发但行为混乱指令模糊或技能冲突细化指令、设置优先级响应变慢加载技能过多精简常驻技能按需加载测试跑不过测试用例与实现不匹配检查测试断言是否合理团队协作冲突技能版本不一致锁定版本号统一升级6. 技能体系的扩展与个人实践体会6.1 从单技能到技能链单个技能能解决的问题有限真正的威力在于技能链。比如一个完整的新功能开发流程可以拆成需求分析技能 → 测试编写技能 → 实现技能 → 重构技能 → 文档生成技能。每个技能负责一段串联起来就是一条自动化流水线。agent-skills支持在skill.json里声明next字段指定当前技能执行完后自动加载的下一个技能。这个机制让技能链的编排变得很自然。我试过用这种方式搭了一条从需求到提交的链路虽然还不能完全无人值守但至少省掉了大量重复的上下文切换。6.2 技能的可测试性是被低估的价值很多人把 agent-skills 当成提示词管理工具我觉得这是低估了它。它真正的价值在于把代理行为纳入了可测试的范畴。你可以给技能写测试用例用固定的输入验证输出这在以前是不可想象的。代理的行为从玄学变成了工程。我现在的习惯是每写一个新技能先写三个测试用例一个正常场景、一个边界场景、一个异常场景。跑通了再接入实际使用。这个习惯让我省了很多调试时间因为大部分问题在测试阶段就暴露了。6.3 我踩过的几个坑第一个坑是技能写得太泛。早期我写了一个代码优化技能触发条件就一个词优化。结果代理在任何涉及代码的任务里都加载这个技能输出一堆无关的优化建议。后来我把触发条件改成性能优化重构优化这类具体词问题才解决。第二个坑是忽略代理的版本差异。同一个技能在不同版本的 Claude Code 里表现不一样因为代理对指令的解析逻辑在迭代。解决办法是在skill.json里声明兼容的代理版本范围避免在不兼容的环境里使用。第三个坑是技能仓库没有文档。团队里其他人不知道有哪些技能可用、每个技能干什么。后来我加了一个自动生成的技能索引每次提交时更新问题才缓解。技能的可发现性和技能本身一样重要。6.4 后续可以怎么扩展如果你已经把基础技能跑通了可以考虑这几个方向。一是技能的市场化分发把通用技能打包发布团队之间共享。二是技能与 CI 集成在代码提交时自动跑相关技能把代理能力嵌入到质量门禁里。三是技能的效果度量记录每个技能的触发次数、成功率、用户反馈用数据驱动技能优化。我个人最看好的方向是技能与测试驱动开发的深度结合。当代理能稳定地先写测试再写实现代码质量的基线就被抬高了。这不是靠模型变强实现的而是靠工程化的技能体系约束出来的。agent-skills提供的正是这套约束的基础设施剩下的就看你怎么用它了。