1. agent-skills 到底在解决什么问题第一次看到agent-skills这个词很多人会以为它又是一个给 AI 加技能包的营销概念。但如果你真的在用 Claude Code 这类 AI coding agent 写代码就会明白它戳中的是一个很具体的痛点agent 每次干活都像失忆的新人你昨天教它的规范、踩过的坑、项目约定今天它全忘了。我自己的经历很典型。项目里有一套约定俗成的错误处理方式比如所有对外接口必须返回统一的错误码结构日志必须带 traceId。我每次开新会话都要重新跟 agent 解释一遍解释完它写得挺好会话一关下次又得从头来。这种重复劳动累积起来非常消耗耐心而且 agent 偶尔会自由发挥写出跟项目风格完全不符的代码。agent-skills这个方向要解决的就是把这套项目知识沉淀成 agent 可以自动加载、按需调用的技能单元。你可以把它理解成给 agent 准备的一本可执行的团队手册不是写在 wiki 里没人看而是 agent 在动手前会自动翻阅、动手时会主动遵守。关键词里出现的skills CLI、test-driven-development其实已经点明了它的两个核心特征——有命令行工具来管理技能而且技能本身可以承载像 TDD 这样的完整工作流。这篇文章适合三类人看一是已经在用 Claude Code 或类似 AI coding agent、但被重复解释折磨的开发者二是想给团队建立 AI 编码规范、让 agent 输出更可控的技术负责人三是单纯好奇 agent 能力扩展机制、想搞明白技能和提示词到底差在哪的工程师。我会从概念拆解讲到落地实操把能直接抄的配置和踩过的坑都摊开说。需要先说明一点agent-skills目前没有一个绝对权威的单一实现不同工具链对skill的定义有差异。下面讲的内容是基于这类系统常见的工程实践做的合理归纳具体到你用的工具细节上可能有出入但底层逻辑是通的。2. 拆开 agent-skills 的骨架技能、触发与加载2.1 一个 skill 到底由什么组成把 skill 想象成一个带说明书的工具箱。它通常包含三部分元信息、指令正文、可选的辅助资源。元信息负责回答这个技能是干什么的、什么时候该用。一般会有名称、一句话描述、以及触发条件。触发条件是最关键的部分它决定了 agent 在什么场景下会想起这个技能。比如一个数据库迁移技能触发条件可能是当任务涉及修改表结构或新增字段时。指令正文是技能的核心用自然语言写清楚具体怎么做。这里有个常见误区很多人把指令写得像 API 文档干巴巴列参数。实际上 agent 更吃场景化描述比如新增字段时先写 migration 文件再更新 model最后补一条回滚脚本注意字段默认值不能为空——这种带顺序、带约束的写法agent 执行起来准确率高得多。辅助资源则是可选项可以放代码模板、示例文件、检查清单。有些实现支持 skill 引用外部文件agent 需要时再去读这样能避免把所有内容都塞进上下文节省 token。2.2 触发机制agent 怎么知道该用哪个技能这是整个体系里最容易被低估的部分。技能写得再好agent 想不起来用等于零。常见的触发方式有三种。第一种是描述匹配agent 拿到任务后把任务描述和所有 skill 的描述做语义比对选出相关的。这种方式灵活但不够精确描述写得含糊就会漏触发或误触发。第二种是显式调用你在对话里直接说用 XX 技能来做适合你明确知道该用哪个的场景。第三种是规则触发基于文件路径、文件类型、命令关键词等硬条件触发比如只要改动.sql文件就加载数据库技能。实测下来描述匹配 规则触发组合最稳。纯靠语义匹配agent 经常在边缘场景犯迷糊纯靠规则又覆盖不了那些没有明显文件特征的任务。我一般会把高频、边界清晰的技能配上规则触发把偏软性的规范类技能交给描述匹配。2.3 加载时机为什么不能一次性全塞进去有人会想既然技能有用那全加载不就行了问题在于上下文窗口是有限资源。你把二十个技能的完整正文全塞进 system promptagent 的注意力会被稀释真正干活时反而抓不住重点而且 token 成本飙升。合理的做法是渐进式加载启动时只加载所有技能的元信息名称 描述这部分很轻量当 agent 判断某个技能相关时再把它的完整正文拉进来。这就像你书架上摆着几十本书你不需要背下每本书的内容只需要知道每本书讲什么需要时再翻开。下面这张表对比了几种加载策略的取舍是我在实际项目里权衡后总结的加载策略上下文占用触发准确率适用场景全量加载极高高但注意力分散技能数量少于 5 个仅元信息 按需加载低中高技能数量 10 个以上纯规则触发低依赖规则质量文件特征明显的任务描述匹配 规则混合中高大多数生产场景提示技能数量超过 15 个之后元信息本身也会占用可观上下文。这时候要考虑给技能分组或者用更精简的描述。3. 用 skills CLI 把技能管起来3.1 为什么需要一个命令行工具手工维护技能文件一开始还行技能一多就乱命名不统一、版本对不上、团队里每个人本地改的还不一样。skills CLI这类工具的价值就是把技能当成代码资产来管理——有目录结构、有版本、能安装能卸载、能同步。它的典型能力包括初始化技能目录、从模板创建新技能、列出已安装技能、校验技能格式、把技能安装到 agent 的配置目录。你可以把它类比成npm之于前端包或者pip之于 Python 库只不过管理的是给 agent 看的技能。3.2 目录结构怎么组织一个清晰、可扩展的目录结构能省掉后面无数的麻烦。我推荐按领域 技能两级来分skills/ backend/ error-handling/ SKILL.md templates/ db-migration/ SKILL.md frontend/ component-style/ SKILL.md workflow/ tdd/ SKILL.md checklist.md每个技能一个独立目录主文件统一叫SKILL.md或工具约定的名字辅助资源放同目录的子文件夹。这样组织的好处是技能之间互不干扰迁移和复用都方便团队协作时冲突面小。3.3 写一个能真正被触发的技能光有目录不够技能内容写得好不好直接决定 agent 用不用、用得对不对。我总结了一个三段式写法实测触发率和执行准确率都不错。第一段是触发场景用一两句话描述什么时候该用我。要写得具体避免处理代码相关任务这种大而空的话。比如当需要新增或修改数据库表结构时使用。第二段是执行步骤按顺序列出动作。每步尽量包含做什么 注意什么。比如1. 在 migrations 目录新建带时间戳的文件2. 写 up 和 down 两个函数down 必须能完整回滚3. 字段默认值不能为空除非有明确理由。第三段是检查清单列出完成后的自检项。这部分对 agent 特别有用它会在收尾时对照检查减少遗漏。--- name: db-migration description: 当需要新增或修改数据库表结构时使用 trigger: paths: - **/migrations/** - **/*.sql --- ## 触发场景 涉及表结构变更、字段增删、索引调整时。 ## 执行步骤 1. 在 migrations 目录新建带时间戳的迁移文件 2. 编写 up 与 down 函数down 必须可完整回滚 3. 新增字段需指定默认值避免线上写入失败 4. 大表加索引需评估锁表风险必要时用在线 DDL ## 检查清单 - [ ] down 函数能回滚 up 的所有改动 - [ ] 新增非空字段有默认值 - [ ] 迁移文件命名符合时间戳规范3.4 版本与同步团队协作绕不开的坎技能一旦进入团队协作就会遇到我改了技能别人不知道的问题。解决办法是把技能目录纳入版本控制跟代码一起走 Git 流程。谁改了技能走 PR 评审合并后大家拉取更新。skills CLI通常提供安装/同步命令把仓库里的技能同步到本地 agent 配置目录。这里有个坑不同人的 agent 配置目录路径可能不一样尤其是跨操作系统。建议在项目里放一个说明文件写清楚各平台的配置路径或者干脆用 CLI 的默认约定减少手工配置。注意技能同步是单向的从仓库到本地不要在本地直接改同步过来的技能否则下次同步会被覆盖。要改就改仓库里的源文件。4. 把 TDD 工作流塞进技能里4.1 为什么 TDD 特别适合做成技能关键词里专门点了test-driven-development这不是偶然。TDD 是一套有严格顺序、有明确检查点的工作流天然适合写成技能让 agent 遵守。它的核心循环是红-绿-重构先写一个会失败的测试再写刚好能让它通过的代码最后在测试保护下重构。问题在于agent 默认的行为往往是先写实现再补测试甚至干脆不写测试。你如果只在对话里说一句用 TDD它可能理解成记得写测试而不是严格执行那个循环。把 TDD 写成技能就能把顺序和约束固化下来。4.2 技能里怎么描述红绿重构关键在于把每一步的完成标准写清楚让 agent 有明确的什么时候算这步做完了。红阶段写一个测试运行它必须看到它失败而且失败原因是因为功能没实现不是因为语法错误或测试本身写错。这一步很多人会跳过确认失败直接写测试就写实现结果测试到底测没测到东西都不知道。绿阶段写最少的代码让测试通过。注意是最少不是顺便把其他功能也实现了。agent 很容易在这里过度发挥把后面几步的活一起干了导致测试覆盖不到。重构阶段在测试全绿的前提下调整代码结构每次重构后重跑测试。这一步的约束是不改变外部行为。4.3 一个可复用的 TDD 技能片段--- name: tdd-workflow description: 当需要实现新功能或修复 bug 时按测试驱动方式推进 --- ## 触发场景 新增功能、修复缺陷、重构既有逻辑时。 ## 执行步骤 1. 红先写测试运行并确认失败失败原因须为功能缺失 2. 绿写最少代码使测试通过不提前实现未覆盖功能 3. 重构测试全绿后优化结构每次改动后重跑测试 4. 循环重复以上步骤直到需求完成 ## 检查清单 - [ ] 每个测试都经历过确认失败这一步 - [ ] 实现代码没有超出测试覆盖范围 - [ ] 重构后所有测试仍通过4.4 实测中 agent 会怎么偷懒即便写了技能agent 还是会有一些惯性行为需要你盯着。最常见的是跳过确认失败它写完测试直接写实现然后跑一次测试发现通过了就报告完成。这时候你根本不知道测试是不是真的有效——有可能测试写错了永远通过。另一个是测试写得过宽一个测试断言了一大堆东西失败时定位困难。我会在技能里加一条约束每个测试只验证一个行为逼它拆细。还有个隐蔽的坑agent 在绿阶段为了让测试通过可能会去改测试而不是改实现。这完全违背 TDD 精神。技能里要明确写测试是需求的表达不允许为了让测试通过而修改测试断言除非需求本身变了。5. 在 Claude Code 里落地 agent-skills 的实操路径5.1 环境准备阶段容易忽略的细节在 Claude Code 里用技能第一步是把技能放到它认识的位置。不同版本、不同安装方式桌面版、VS Code 插件、命令行的配置目录可能不同这是最容易卡住新手的地方。我的建议是先用 CLI 的初始化命令生成默认目录结构别自己猜路径。生成后确认一下目录里有没有示例技能有的话说明路径对了。然后把你自己的技能放进去重启 agent 或触发一次重新加载。如果你是在 VS Code 里用 Claude Code 插件注意插件的配置可能和命令行版本不完全共享。我遇到过命令行里技能生效、插件里不生效的情况排查下来是插件读的是另一个配置目录。解决办法是在插件设置里显式指定技能目录路径。5.2 技能生效的验证方法技能放好了不代表生效了。验证方法很简单构造一个应该触发该技能的任务看 agent 的行为是否符合技能描述。比如你放了一个错误处理技能要求所有接口返回统一错误结构。那就让 agent 写一个新接口看它返回的错误格式对不对。如果不对先别急着改技能内容先确认技能有没有被加载——可以在对话里直接问 agent你现在有哪些技能可用看它列出来的清单里有没有你的技能。如果技能加载了但没触发问题多半出在描述上。把描述改得更贴近你实际会说的任务语言比如你平时说加个接口描述里就别只写RESTful API 开发把新增接口这种口语也带上。5.3 和模型接入相关的注意事项热词里提到了用第三方模型接入 Claude Code 的场景。这里要提醒的是不同模型对技能指令的遵循程度差异很大。有些模型对结构化指令带编号的步骤、检查清单执行得很好有些则容易忽略细节。如果你换了模型之后发现技能突然不灵了先别怀疑技能写错了很可能是模型对指令的解析方式变了。应对办法是把技能写得更啰嗦一点关键约束重复强调或者把长步骤拆成更小的技能。实测下来指令越具体、越少歧义跨模型的稳定性越好。提示技能里的检查清单对弱一些的模型帮助尤其大因为它提供了一个明确的收尾对照表能显著减少遗漏。5.4 技能与项目配置的配合技能不是孤立的它要和项目里的其他配置配合。比如你的项目有 lint 规则、有 CI 流程技能里就应该引用这些让 agent 知道写完代码要跑 lint提交前要过 CI。我一般会在技能里写清楚项目特有的命令比如运行pnpm lint:fix自动修复格式问题测试用pnpm test:unit不要跑全量。这样 agent 就不会瞎猜命令也不会因为跑错命令浪费时间。这些细节看起来琐碎但累积起来能省很多来回。6. 踩过的坑与排查链路6.1 技能写了但 agent 完全不理这是最高频的问题。排查顺序我一般是这样的先确认技能有没有被加载。直接问 agent 它有哪些技能或者看启动日志里有没有加载记录。没加载就是路径问题检查配置目录对不对。加载了但不触发就看描述和触发条件。把 agent 实际收到的任务描述和你的技能描述放一起对比看语义上差多远。差得远就改描述把任务里常见的说法加进去。触发条件里如果用了路径规则检查路径匹配对不对。我踩过一次坑规则写的是**/migrations/**但项目里迁移文件放在db/migrate/下路径根本对不上自然不触发。路径规则一定要拿实际文件路径验证。6.2 技能之间互相打架技能多了之后会出现两个技能都觉得自己该管某件事的情况。比如一个代码风格技能和一个重构技能都涉及改代码结构agent 可能一会儿按这个来一会儿按那个来行为不稳定。解决办法是明确技能边界。在描述里写清楚本技能不负责 XX那部分交给 XX 技能。如果两个技能确实有重叠考虑合并或者用一个上层技能来协调。技能不是越多越好职责清晰比数量重要。6.3 技能内容太长导致被截断技能正文写得太长加载时可能被截断agent 只看到前半部分后面的约束全丢了。这个坑很隐蔽因为表面上技能加载成功了但实际生效的只有一部分。我的经验是单个技能正文控制在合理长度内把详细内容放到辅助文件里技能正文只保留核心步骤和检查清单需要细节时让 agent 去读辅助文件。这样既保证核心约束一定被看到又不丢细节。6.4 更新技能后行为没变化改了技能文件agent 行为却没变多半是缓存问题。有些实现会缓存已加载的技能需要显式重载或重启才生效。养成习惯改完技能先重启 agent 再验证别在旧缓存上瞎调试。还有一种情况是技能同步没成功。你改的是仓库里的源文件但 agent 读的是本地配置目录里的副本中间同步这一步没跑自然没变化。确认一下同步命令有没有执行成功。7. 让技能真正沉淀下来的几个习惯技能体系能不能长期用下去不取决于工具多先进而取决于有没有把它当成活的资产来维护。我自己的几个习惯分享出来供参考。第一每次 agent 犯错先想能不能沉淀成技能。它这次把错误处理写错了别只是当场纠正想想是不是该在技能里加一条约束。纠正一次是解决当下写进技能是解决以后。第二技能要定期清理。项目在变有些技能过时了有些被更好的替代了。留着不用的技能不仅占上下文还可能在触发时干扰判断。我大概每个月过一遍技能列表该删的删该合的合。第三技能描述用团队的真实语言。别用教科书式的术语用大家平时说话的方式写。你平时说加个字段描述里就写加个字段别写执行 schema 变更操作。agent 匹配的是语义越贴近真实表达触发越准。第四给技能写变更记录。谁在什么时候为什么改了这个技能简单记一笔。技能多了之后回头看某个约束的来龙去脉没有记录会很痛苦。最后分享一个我最近才想明白的点技能的价值不在于让 agent 更聪明而在于让 agent 更一致。它不会让 agent 突然会写它本来不会的代码但它能让 agent 每次都按你认可的方式来写。对于团队协作来说一致性往往比单次的惊艳更重要。这也是为什么我越来越愿意在技能上花时间——它是在给整个团队的 AI 协作打地基。
