1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识把它理解成给 AI 助手写提示词。这个理解不算错但太浅了。真正在项目里折腾过 AI coding agents 的人会知道agent-skills本质上是一套可复用、可组合、可版本化的能力封装机制——它把让 AI 完成某类任务这件事从一次性的对话技巧变成了工程资产。我最初接触这个概念是在给团队搭建一套基于 Claude Code 的自动化开发流程时。当时遇到的痛点非常典型同一个写单元测试的需求换个项目、换个目录、换个人来问AI 给出的质量就天差地别。有人写出来的测试覆盖了边界条件有人写出来的测试只是把函数调用了一遍。问题不在模型而在于我们没有把怎么做测试这件事沉淀下来。agent-skills要解决的正是这个沉淀问题。所以这篇内容适合谁看如果你只是偶尔用 AI 补全几行代码那可能用不上但如果你正在把 AI coding agents 接入到真实的研发流程里想让它在团队内稳定输出、想让测试驱动开发这类方法论真正落地那agent-skills这套思路值得你花时间吃透。下面我会从设计思路、核心机制、实操落地、问题排查几个层面把我在实际项目里踩过的坑和总结的方法完整讲一遍。2. agent-skills 的整体设计与思路拆解2.1 为什么需要技能这一层抽象先说一个反直觉的结论直接给 AI 写超长提示词是最不划算的做法。我试过把一份 3000 字的测试规范塞进系统提示里结果模型在前半段还能遵守到后半段就开始偷懒而且每次调用都要重复消耗这些 token成本高、稳定性差。agent-skills的思路是把能力拆成独立的技能单元。每个技能单元包含三部分触发条件什么时候用这个技能、执行步骤具体怎么做、验收标准做到什么程度算完成。这三部分组合起来就形成了一个自包含的能力模块。打个比方这就像餐厅的后厨。你不会每次做菜都从头跟厨师讲一遍先热锅、再放油、油温七成热下料而是把这些固化成菜谱。agent-skills就是 AI 的菜谱库需要哪道菜就调哪本菜谱而不是每次口头复述。这种设计带来的直接好处有三个可组合一个写测试技能可以调用分析函数签名技能再调用生成断言技能像搭积木一样拼装复杂流程。可版本化技能文件可以进 Git改了什么、谁改的、为什么改全都有记录出问题能回滚。可复用同一个技能在 Claude Code、VS Code 插件、CLI 环境里都能用不绑定具体入口。2.2 技能与提示词、工具调用的边界这里必须澄清一个容易混淆的点agent-skills不等于工具调用tool use也不等于系统提示词。三者的分工是这样的层次作用举例系统提示词定义 AI 的身份和全局约束你是一个严谨的后端工程师工具调用让 AI 能操作外部世界读写文件、执行终端命令agent-skills封装完成某类任务的方法论如何为一个函数写 TDD 测试工具调用解决的是能不能做技能解决的是做得好不好。很多人把 AI 接进 IDE 之后觉得效果一般往往就是缺了技能这一层——AI 有手有脚但不知道该按什么章法干活。2.3 方案选型为什么是文件而非数据库在实现层面我强烈建议把技能存成纯文本文件Markdown 或 YAML而不是塞进数据库或某个平台的后台。理由很实在第一可读性。技能是给人看也给 AI 看的Markdown 天然适合。你打开文件就能看懂这个技能在干什么不需要额外的管理界面。第二可移植。文件跟着项目走换台机器、换个 IDE、换个模型技能照样能用。我见过太多团队把配置绑死在某个平台上结果平台一升级整套流程全废。第三可 diff。技能迭代时Git diff 能清楚显示这次把验收标准从能跑通改成了覆盖边界条件这种可追溯性在团队协作里价值极高。提示技能文件的命名建议用动词名词结构比如write-unit-test.md、review-pull-request.md一眼就能看出这个技能是干什么的避免用skill1、helper这种含糊名字。3. 核心细节解析与实操要点3.1 一个技能文件应该包含什么我经过多次迭代最终固定下来的技能文件结构是这样的。以测试驱动开发技能为例# 技能名称TDD 单元测试生成 ## 触发条件 当用户要求为某个函数或模块编写测试或提到 TDD、单元测试时启用。 ## 前置检查 1. 确认目标函数所在的文件路径 2. 读取函数签名和依赖关系 3. 检查项目已有的测试框架jest / pytest / go test 等 ## 执行步骤 1. 先写一个会失败的测试红 2. 运行测试确认失败原因是功能未实现而非语法错误 3. 写最小实现让测试通过绿 4. 重构保持测试通过重构 5. 补充边界条件测试空输入、极值、异常路径 ## 验收标准 - 每个公开函数至少有一个测试 - 边界条件覆盖率不低于 80% - 测试之间相互独立无执行顺序依赖 ## 禁止事项 - 不允许为了让测试通过而修改测试断言 - 不允许跳过失败测试直接写实现这个结构的关键在于验收标准和禁止事项。前者让 AI 知道做到什么程度算完后者防止它走捷径。我踩过最大的坑就是没写禁止事项结果 AI 为了让测试变绿直接把断言改成了expect(true).toBe(true)——测试是过了但毫无意义。3.2 触发条件的写法决定成败触发条件是技能里最容易被写坏的部分。写得太宽AI 会在不该用的时候乱用写得太窄该用的时候又调不起来。我的经验是触发条件要描述用户意图而不是关键词。比如不要写当用户输入测试时触发而要写当用户要求验证某段代码的正确性时触发。前者是字符串匹配后者是语义理解后者鲁棒性高得多。另外多个技能之间要有明确的优先级。比如写测试和重构代码两个技能可能同时被触发这时候需要一个调度规则。我通常会在项目根目录放一个skills/README.md用一张表说明各技能的适用场景和优先级技能适用场景优先级write-unit-test新增功能、修复 bug 后高refactor-code代码异味、重复逻辑中review-pr提交前自检高3.3 技能的组合与嵌套单个技能能做的事有限真正的威力在于组合。举个我实际用过的例子一个实现新功能的完整流程其实是三个技能串联analyze-requirement把需求拆成可执行的子任务write-unit-test为每个子任务先写测试implement-feature写实现让测试通过在 Claude Code 里这种组合可以通过在技能文件里显式引用其他技能来实现。比如在implement-feature.md里写一句本技能执行前需先完成write-unit-test技能的全部步骤。这样 AI 在规划任务时会自动把依赖关系考虑进去。注意技能嵌套不要超过三层。我试过五层嵌套结果 AI 在执行时经常忘记中间某一层导致流程断裂。三层以内模型的上下文还能稳稳记住。3.4 与 CLI 和 IDE 的对接方式agent-skills本身是内容不绑定运行环境。但落地时不同入口的对接方式有差异Claude Code CLI把技能目录放在项目根目录通过配置文件声明技能路径。CLI 启动时会自动加载AI 在对话中按需调用。VS Code 插件在插件配置里指定技能目录插件会把技能内容注入到每次对话的上下文中。注意这里要控制注入量全量注入会撑爆上下文窗口。纯终端环境如果只是用命令行调用模型 API可以在请求里把相关技能内容拼进 system prompt按需加载。我个人的偏好是 CLI 文件目录的方式因为最透明出问题能直接看文件不依赖任何黑盒。4. 实操过程与核心环节实现4.1 环境准备从零搭起技能目录假设你已经在 Ubuntu 或 macOS 上装好了 Claude Code安装方式官方文档写得很清楚这里不展开接下来是搭建技能目录。我的目录结构是这样的project-root/ ├── .claude/ │ └── skills/ │ ├── README.md │ ├── write-unit-test.md │ ├── refactor-code.md │ └── review-pr.md ├── src/ └── tests/创建命令很简单mkdir -p .claude/skills touch .claude/skills/README.md然后在 Claude Code 的配置里声明这个路径。不同版本的配置字段名可能略有差异核心是让 CLI 知道去哪里找技能文件。配置完成后重启 CLI输入一个测试需求观察 AI 是否按技能里的步骤执行。4.2 编写第一个技能以 TDD 为例我建议第一个技能就写 TDD因为它流程清晰、验收标准明确最容易验证效果。具体步骤第一步确定测试框架。先看项目里有没有现成的测试配置。Node 项目看package.json里的jest或vitestPython 项目看pytest是否在依赖里。这一步不能省否则 AI 会按自己的习惯选框架跟项目对不上。第二步写触发条件。用自然语言描述用户意图比如当用户要求为函数编写测试、提到 TDD、或修复 bug 后需要回归验证时。第三步写执行步骤。严格按红-绿-重构的顺序写每一步都要有可验证的产出。比如红这一步的产出是一个运行后失败的测试文件。第四步写验收标准。这里要具体到可量化比如边界条件覆盖率不低于 80%而不是测试要全面。第五步写禁止事项。把你知道的所有AI 会偷懒的路径都堵上比如禁止修改断言、禁止跳过失败步骤。写完之后拿一个真实的函数试跑。我当时的测试对象是一个字符串处理函数AI 按技能执行后确实先写了失败测试再写实现最后补了空字符串和超长字符串的边界测试。整个过程比我手动写快了大概三倍而且质量稳定。4.3 参数与配置的取舍逻辑技能文件里有些参数需要你根据项目实际情况调整这里说几个关键的上下文注入量。如果技能文件太长每次对话都全量注入会浪费 token。我的做法是把技能分成核心步骤和详细说明两部分核心步骤常驻详细说明按需加载。具体阈值上单个技能文件控制在 500 行以内比较稳妥。触发阈值。有些技能需要设置置信度阈值比如只有当 AI 判断用户意图匹配度超过某个值时才启用该技能。这个阈值没有标准答案我的经验是从 0.7 起步观察误触发率再调整。超时与重试。如果技能里包含执行终端命令的步骤要设置合理的超时。比如跑测试的超时设成 60 秒超过就判定为失败并让 AI 检查原因而不是无限等待。4.4 一次完整的实操记录我拿一个真实场景走一遍。需求是给一个计算订单折扣的函数写测试。AI 加载write-unit-test技能后先执行前置检查读取函数签名发现它接收orderAmount和userLevel两个参数返回折扣后的金额。然后检查项目测试框架发现是 jest。接着进入执行步骤。第一步写失败测试test(VIP 用户订单满 100 应打 8 折, () { expect(calculateDiscount(150, VIP)).toBe(120); });运行后失败因为函数还没实现。第二步写最小实现function calculateDiscount(amount, level) { if (level VIP amount 100) return amount * 0.8; return amount; }测试通过。第三步重构把魔法数字提取成常量。第四步补边界测试金额为 0、金额刚好 100、未知用户等级。全部通过后技能判定验收标准达成输出总结。整个过程 AI 没有跳步也没有改断言。这就是技能文件里禁止事项起作用的结果。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。AI 明明该用某个技能却直接凭感觉回答了。排查顺序如下先检查技能文件是否被正确加载。在 Claude Code 里可以输入一个诊断命令看它列出了哪些已加载的技能。如果列表里没有你的技能说明路径配置有问题。再检查触发条件的措辞。如果写得太学术化比如当需要进行单元级别的验证性测试构造时模型可能理解不到位。改成大白话当用户要求写测试时命中率立刻上升。最后检查是否有其他技能抢了触发。如果两个技能的触发条件重叠模型可能选了另一个。这时候要么调整优先级要么把触发条件写得更互斥。5.2 技能执行到一半跑偏这种情况通常是上下文丢失导致的。技能步骤太长模型执行到后面忘了前面。解决办法有两个一是把长技能拆成多个短技能用组合的方式串联二是在每个步骤末尾加一句回顾本步骤的产出是 XXX下一步将基于它做 YYY帮模型保持记忆。我实测下来单个技能的执行步骤控制在 7 步以内跑偏率会大幅下降。5.3 不同模型下表现不一致同一个技能在 Claude 上跑得好换到别的模型可能就拉胯。这不是技能的问题是模型能力差异。我的应对策略是技能分层核心逻辑写成模型无关的通用版本针对特定模型的调优写成可选的覆盖层。这样换模型时只需要调整覆盖层不用重写整个技能。5.4 常见问题速查表问题现象可能原因解决方向技能完全不触发路径未配置 / 触发条件太窄检查加载列表改宽触发描述执行中途跑偏步骤过长 / 上下文丢失拆分技能加回顾提示验收标准不达标标准太模糊改成可量化指标换模型后失效模型能力差异技能分层加覆盖层技能之间冲突触发条件重叠明确优先级互斥化描述5.5 几个我踩过的坑第一个坑是技能文件里写了太多背景知识。我一开始把 TDD 的历史、原理、好处全写进去了结果模型被这些内容带偏执行时总想先解释一下 TDD 的意义。后来我把背景知识全删了只留可执行步骤效果立刻变好。技能文件是给 AI 执行用的不是给人科普用的。第二个坑是验收标准写成了主观描述。比如测试要写得优雅这种标准 AI 根本没法判断。改成每个测试只断言一个行为就可执行了。第三个坑是忽略了技能的维护成本。技能写完不是终点项目演进后技能也要跟着改。我现在的做法是每个技能文件头部加一个最后更新日期和适用版本定期回顾避免技能和项目脱节。6. 技能库的扩展与团队协作6.1 从个人技能到团队资产一个人用技能和团队用技能是两回事。个人用怎么方便怎么来团队用必须考虑一致性。我的做法是建立一个技能评审机制任何人新增或修改技能都要经过一次 review重点看触发条件是否清晰、验收标准是否可量化、禁止事项是否覆盖了已知的偷懒路径。评审通过后技能进主分支所有人共享。这样能避免每个人一套技能的混乱局面。6.2 技能与项目规范的绑定技能库最好和项目的编码规范绑定。比如项目规定所有公开函数必须有 JSDoc 注释那就在相关技能的验收标准里加上这一条。这样 AI 在写代码时会顺带把注释补上省去人工检查。我见过一个团队把 ESLint 规则直接翻译成技能里的禁止事项效果非常好。AI 写出来的代码lint 通过率从 60% 提升到了 95% 以上。6.3 持续迭代的节奏技能库不是一次建成的。我的节奏是每完成一个迭代周期回顾一次技能库把新踩的坑补进禁止事项把新的验收标准加进去。这个过程不需要很频繁两周一次足够。关键是坚持让技能库跟着项目一起成长。提示给技能库建一个 changelog记录每次修改的原因。半年后回头看你会发现这份 changelog 本身就是一份宝贵的团队经验沉淀。7. 关于 agent-skills 的一些个人体会折腾agent-skills这套东西大半年我最大的感受是它考验的不是 AI 的能力而是你自己的工程能力。你能不能把一个模糊的需求拆成清晰的步骤能不能定义出可量化的验收标准能不能预判执行过程中会出什么岔子——这些能力跟 AI 无关是每个工程师的基本功。技能库写得好的人往往本身就是做事有条理的人。反过来如果你发现自己写技能时总是卡壳那可能不是 AI 的问题而是你对这件事本身的理解还不够透彻。从这个角度看agent-skills其实是一面镜子照出的是你自己的工程素养。最后分享一个小技巧刚开始别贪多先写一个技能用一周改一周等它稳定了再写第二个。技能库的价值在于质量而非数量十个半吊子技能不如一个打磨到位的技能。