agent-skills：为AI编程助手构建可复用技能库的工程实践

1. 从“装完就吃灰”说起agent-skills 到底解决了什么问题如果你最近半年在折腾 AI coding agents大概率经历过这个循环兴冲冲装好 Claude Code 或者 Cursor敲了几个 prompt发现它确实能补全代码、能解释报错但一旦任务稍微复杂一点——比如“帮我把这个模块重构一下顺便补上单元测试再更新一下文档”——它就开始飘了。要么只改了主逻辑忘了测试要么文档格式完全不对要么干脆在某个文件里绕圈子出不来。问题不在于模型不够聪明而在于你给它的“技能包”太薄了。agent-skills这个项目本质上就是给 AI coding agents 装上一套可复用、可组合、可版本管理的“技能库”。你可以把它理解成给 agent 写的“标准作业程序SOP集合”每个 skill 是一个独立目录里面用 Markdown 描述这个技能什么时候触发、需要哪些输入、按什么步骤执行、输出什么格式、有哪些边界条件。agent 在运行时通过skills CLI扫描这些目录把匹配的技能加载进上下文然后按技能里定义的流程去干活。这件事为什么重要因为目前主流 agentClaude Code、Cursor 的 Agent 模式、以及各种基于开源模型搭建的 coding agent都有一个共同的短板它们对“项目级约定”的记忆是临时的。你这次告诉它“测试文件要放在__tests__目录下用 vitest 不用 jest”下次开新会话它又忘了。而 agent-skills 把这些约定从“对话历史”里抽出来变成磁盘上可持久化的文件agent 每次启动都能读到。适合谁来参考这篇内容三类人第一类是把 Claude Code 或 Cursor 当日常主力工具、但总觉得“差一口气”的开发者第二类是团队里负责搭建 AI 辅助开发流程的技术负责人第三类是想自己写 agent 工具链、需要一套技能加载机制参考的工程师。哪怕你只是刚装好 Claude Code 的新手理解这套机制也能让你少走很多弯路——因为热词里反复出现的“claude code skills 安装”“claude code 配置”核心就是在配这个东西。2. 拆开看agent-skills 的整体设计与选型逻辑2.1 为什么是“目录 Markdown”而不是插件或 API第一次看到 agent-skills 的设计时我脑子里冒出的问题是为什么不做成 npm 包或者插件系统后来自己写了几轮 skill 才明白Markdown 目录方案的核心优势是“零构建、可热改、人和 agent 都能读”。插件系统需要注册、需要编译、需要处理版本冲突而 skill 就是一个文件夹里面一个SKILL.md加若干辅助文件。你改完保存agent 下次扫描就能生效不需要重启进程。更重要的是Markdown 是 LLM 天然友好的格式——它不需要你把技能逻辑翻译成 JSON schema 或者函数签名直接用自然语言写清楚“什么时候用、怎么用”就行。从选型角度看这套设计明显借鉴了几个成熟思路Unix 的“一切皆文件”、Ansible 的“声明式任务描述”、以及 prompt engineering 里“把指令和上下文分离”的原则。它没有发明新概念而是把已有的最佳实践固化成了目录结构。2.2 技能加载的触发机制匹配比检索更重要agent-skills 的 CLI 在启动时做的主要事情是扫描 匹配。扫描好理解就是遍历配置的技能目录匹配才是关键——它需要根据当前任务描述决定加载哪些 skill 进上下文。这里有个容易踩的坑很多人写 skill 时把触发条件写得太宽泛比如“当用户要求写代码时使用”。结果 agent 每次写代码都加载这个 skill上下文被塞满反而降低了推理质量。正确的做法是把触发条件写具体比如“当用户要求为现有 React 组件补充单元测试且项目使用 vitest 时使用”。匹配精度上去了加载的技能数量才能控制住。我实测下来一个会话里同时加载 3 到 5 个 skill 是比较舒服的区间。超过 8 个agent 就开始出现“指令打架”的情况——两个 skill 对同一个操作给了不同步骤它不知道该听谁的。2.3 与 Claude Code、Cursor 的集成方式差异热词里同时出现了 Claude Code 和 Cursor这两者对 agent-skills 的集成方式其实不太一样值得单独说清楚。Claude Code 的集成更“原生”一些。它本身就有读取项目内 Markdown 指令文件的能力比如CLAUDE.mdagent-skills 相当于把这套机制扩展成了多文件、可分类的技能库。你在 Claude Code 里配置 skills 目录后它会在每次任务开始时自动扫描按需加载。这也是为什么热词里“claude code skills 安装”搜索量很高——很多人装完 Claude Code 后第一件事就是配这个。Cursor 的集成则更依赖它的 Agent 模式和.cursorrules体系。Cursor 本身对项目级规则的支持是通过.cursorrules文件实现的agent-skills 可以作为.cursorrules的补充——把细粒度的技能描述放在 skills 目录里.cursorrules里只写“去扫描 skills 目录并按需加载”。这样做的原因是 Cursor 的规则文件如果写太长会影响它的响应速度而拆成多个 skill 文件后只有匹配到的才会进上下文。提示无论用哪个 agentskills 目录都建议放在项目根目录下不要放在node_modules或用户主目录里。放在项目内才能跟着 git 走团队成员拉下来就能用这是“项目级约定持久化”的关键。3. 核心细节解析一个合格 skill 的解剖结构3.1 SKILL.md 的必备字段与写法一个标准的 skill 目录长这样skills/ write-unit-test/ SKILL.md examples/ react-component.test.ts templates/ test-template.tsSKILL.md是入口文件里面通常包含这几个部分名称与描述、触发条件、前置检查、执行步骤、输出格式、边界与禁忌。我拿一个真实在用的“补单元测试”skill 举例把关键字段拆开讲。名称与描述要短一句话说清这个技能干什么比如“为 React 组件生成 vitest 单元测试”。触发条件要写成“当……且……时使用”的句式把技术栈和场景都框进去。前置检查是很多人会忽略的部分但它极其重要——比如“确认项目 package.json 里有 vitest 依赖”“确认目标组件文件存在且导出了默认组件”。这些检查让 agent 在动手前先验证环境避免它在一个没有测试框架的项目里硬写测试文件。执行步骤要写成有序列表每步一个动作不要合并。比如“1. 读取目标组件源码2. 识别组件的 props 和状态3. 按模板生成测试文件4. 运行测试命令验证”。输出格式要明确是生成文件、修改文件还是只输出建议。边界与禁忌写清楚什么情况下不该用这个 skill比如“如果组件依赖了浏览器 API 且项目没有 jsdom 配置不要使用本技能”。3.2 触发条件的粒度控制从“太宽”到“刚好”我踩过的最大坑就是触发条件写太宽。早期我写了一个“代码审查”skill触发条件写的是“当用户要求审查代码时”。结果每次我让 agent 改个 bug它都先加载这个 skill然后开始给我输出一堆审查意见完全偏离了“改 bug”的主线任务。后来我把触发条件改成了“当用户明确要求进行代码审查且提供了具体的文件路径或 diff 时使用”。这样改完之后agent 只在真正需要审查时才加载它日常改代码不再被干扰。判断粒度是否合适的标准很简单如果你把这个 skill 的触发条件念给一个同事听他能不能准确判断出“现在该不该用”。如果他说“看情况”那就是太宽了如果他说“哦那现在确实该用”那就是刚好。3.3 技能之间的依赖与冲突处理当项目里 skill 数量超过十个之后依赖和冲突就不可避免了。比如“生成 API 路由”skill 和“生成数据库模型”skill前者可能依赖后者先执行。agent-skills 本身没有强制的依赖声明机制但可以通过在 SKILL.md 里写“前置技能”字段来软性约定。冲突处理更麻烦。两个 skill 如果对同一个操作给了不同指令agent 会随机选一个执行结果不可预测。我的做法是在项目级加一个skills/README.md里面维护一张技能关系表标明哪些技能互斥、哪些有先后顺序。这张表不进 agent 上下文但给人看方便团队维护时排查问题。技能 A技能 B关系处理方式生成 API 路由生成数据库模型依赖A 的 SKILL.md 里注明需先执行 B代码审查快速修复互斥同一会话只加载其中一个补单元测试重构模块顺序先重构后补测试反之会白写注意技能冲突最隐蔽的表现是 agent“反复横跳”——它先按 A 改了文件又按 B 改回去。遇到这种情况先检查是不是加载了互斥的技能。4. 实操过程从零搭一套可用的 skills 库4.1 环境准备与 CLI 安装假设你用的是 Claude Code并且项目是一个 TypeScript 的 React 项目。第一步是确认 Claude Code 已经装好并能正常运行。热词里“claude code 安装”“claude code 安装教程”搜索量很高说明这一步就卡住了不少人。基本流程是确认 Node 版本在 18 以上通过官方渠道获取安装方式装完后在终端里能调起claude命令即可。然后是 skills CLI。agent-skills 项目本身提供了一个 CLI 工具用来初始化目录、校验 skill 格式、以及列出当前可加载的技能。安装方式通常是把它作为项目 devDependency 引入或者全局安装后在项目里调用。我建议作为项目依赖引入这样版本跟着项目走团队里每个人用的 CLI 版本一致避免“我这边能加载你那边加载不了”的问题。初始化命令跑完后项目根目录会多出一个skills/文件夹和一个配置文件。配置文件里主要配两件事skills 目录的路径以及加载策略是按需匹配还是全量加载。按需匹配是默认也是推荐的策略。4.2 写第一个 skill以“补单元测试”为例我拿“补单元测试”这个场景完整走一遍。首先在skills/下建目录write-unit-test/然后创建SKILL.md。触发条件我写成“当用户要求为 React 组件补充单元测试且项目 package.json 中包含 vitest 依赖时使用本技能。”前置检查写三条确认 vitest 已安装、确认目标组件文件路径有效、确认项目有 vitest 配置文件。执行步骤我拆成五步读取组件源码、提取 props 类型和关键分支、按模板生成测试文件、把测试文件写到组件同级的__tests__目录、运行npx vitest run验证。输出格式明确为“生成一个新的测试文件不修改组件源码”。模板文件放在templates/test-template.ts里面是一个带占位符的测试骨架。examples 目录放一个真实组件的测试示例给 agent 做 few-shot 参考。实测下来有 examples 的 skill 比没有的执行准确率高出一大截因为 agent 能直接模仿示例的结构和风格。4.3 在 Claude Code 和 Cursor 里分别验证写完 skill 后在 Claude Code 里验证的方式是新开一个会话输入“帮我给src/components/Button.tsx补一下单元测试”。如果 skill 配置正确你应该能看到 agent 先做前置检查比如它可能会说“确认 vitest 已安装”然后按步骤执行最后跑测试。在 Cursor 里验证稍微不同。Cursor 的 Agent 模式需要你在.cursorrules里加一句“扫描 skills 目录按需加载匹配的技能”。然后同样输入上面的指令观察它的行为。我实测发现 Cursor 对 skill 的加载有时会有延迟第一次可能不触发需要重新发起一次请求。这不是 skill 写错了是 Cursor 的上下文管理机制导致的多试一次就好。提示验证 skill 时建议先用一个简单任务跑通再上复杂任务。直接拿复杂任务验证一旦失败你很难判断是 skill 逻辑问题还是任务本身太难。4.4 参数选择与配置调优skills CLI 的配置文件里有几个参数值得调。第一个是maxSkillsPerSession控制单次会话最多加载几个 skill默认可能是 5我建议根据项目复杂度调到 3 到 6 之间。第二个是matchThreshold控制触发条件匹配的严格程度调高会减少误加载但可能漏加载调低反之。第三个是cacheEnabled开启后 skill 内容会被缓存加快加载速度但改完 skill 后需要手动清缓存才生效。我的调优经验是先跑一周默认配置观察 agent 的行为再针对性调整。一上来就调参数你根本不知道每个参数的实际影响是什么。5. 常见问题与排查技巧实录5.1 skill 不触发从匹配日志入手最常见的问题就是“我写了 skill 但 agent 不用”。排查第一步是看 CLI 的匹配日志。大多数 skills CLI 都支持--verbose或--debug参数开启后能看到它扫描了哪些 skill、每个 skill 的匹配得分是多少、最终加载了哪些。如果日志显示你的 skill 匹配得分很低大概率是触发条件写得太窄或者用词和用户输入对不上。比如你写“当用户要求补充测试时”但用户实际说的是“帮我写点测试”语义匹配可能就偏了。解决办法是在触发条件里把常见的同义表达都列上或者用更通用的动词。如果日志显示匹配得分很高但没加载检查maxSkillsPerSession是不是被其他 skill 占满了。这种情况在项目 skill 多的时候很常见。5.2 skill 加载了但执行跑偏检查指令冲突agent 加载了 skill 但没按步骤执行通常有两个原因。一是 skill 内部指令有歧义比如“读取组件源码”没写清楚是读整个文件还是只读导出部分。二是多个 skill 指令冲突agent 在两者之间摇摆。排查方法是临时把其他 skill 移走只留这一个看它是否正常执行。如果正常说明是冲突问题如果还是跑偏说明是 skill 本身写法问题。skill 写法问题里最常见的是步骤太粗比如只写“生成测试文件”而不写“按 templates 目录下的模板生成”agent 就会自由发挥。5.3 跨平台差异Windows 和 macOS 的坑热词里出现了“claude code win11”和“mac cursor”说明跨平台使用是真实场景。agent-skills 本身是跨平台的但 skill 里如果写了 shell 命令就要注意差异。比如路径分隔符、命令别名、环境变量写法Windows 和 macOS 都不一样。我的做法是在 skill 里尽量用跨平台的命令比如用npx vitest run而不是./node_modules/.bin/vitest。如果实在避不开平台差异就在 SKILL.md 里写清楚“本技能假设运行环境为 macOS/Linux”让 Windows 用户自己调整。常见问题排查方向解决方式skill 不触发看匹配日志得分放宽触发条件补充同义表达加载了但跑偏检查指令冲突临时移走其他 skill 单独验证执行报错检查前置依赖在 SKILL.md 里补前置检查步骤跨平台失败检查 shell 命令改用跨平台命令或注明环境要求改完不生效检查缓存清缓存或关闭 cacheEnabled5.4 独家避坑skill 不是越多越好我见过有人一口气写了三十多个 skill结果 agent 每次启动要扫描半天加载进来的技能还互相打架。skill 库需要像代码一样维护定期清理不再使用的、合并功能重叠的、拆分过于复杂的。我的维护节奏是每两周过一遍 skills 目录看哪些 skill 最近没被触发过哪些触发后 agent 执行成功率低。没触发的考虑删掉或改触发条件成功率低的考虑重写步骤。这套维护动作看起来麻烦但比“agent 天天跑偏然后你手动擦屁股”省时间得多。6. 技能库的扩展方向与团队协作实践6.1 从个人 skill 到团队 skill 库个人用的时候skill 怎么写都行。但一旦团队多人共用就需要约定。我们团队现在的做法是skill 目录进 git每个 skill 的修改走 PR 流程。PR 里要说明改了什么、为什么改、在哪个 agent 上验证过。这样做的原因是 skill 直接影响 agent 行为改错了会导致全团队的 agent 都跑偏必须有人把关。另外我们加了一个skills/CHANGELOG.md记录每个 skill 的变更历史。当某个 skill 改完后 agent 行为异常可以快速回滚到上一个版本。6.2 把 skill 和项目文档打通skill 里经常需要引用项目约定比如“测试文件放在__tests__目录”“API 路由用 kebab-case 命名”。这些约定如果散落在各个 skill 里改起来很痛苦。我们的做法是在项目根目录维护一个CONVENTIONS.mdskill 里只写“遵循 CONVENTIONS.md 中的测试文件命名约定”具体内容指向那个文件。这样约定改一处所有 skill 都跟着变。6.3 后续可以扩展的方向这套机制跑顺之后能扩展的方向不少。一个是按任务类型分组加载比如“重构类任务”加载一组 skill“新功能类任务”加载另一组减少无关技能干扰。另一个是给 skill 加执行结果反馈记录每个 skill 触发后的任务成功率用数据驱动 skill 的优化。还有一个是把 skill 和 CI 打通在 CI 里跑一遍 skill 校验确保格式正确、没有循环依赖。我个人在实际操作中的体会是agent-skills 这类工具的价值不在于它多复杂而在于它把“和 agent 协作的经验”从脑子里搬到了磁盘上。你踩过的坑、总结的步骤、约定的格式写进 skill 之后就成了团队资产下次换人、换 agent、换项目直接复用就行。最后再分享一个小技巧写 skill 时多用“如果……则……”的句式把分支情况写清楚agent 执行时的稳定性会明显提升。