1. 从“agent-skills”说起为什么我们需要给AI编码代理装上技能包第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给AI编码代理AI coding agents定义、分发、复用“技能”的机制。你可以把它理解成给一个刚入职的聪明实习生发一本《岗位操作手册》手册里写清楚遇到什么场景、该调用什么工具、按什么步骤执行、验收标准是什么。没有这本手册实习生也能干活但干得随机、不稳定、每次都要重新教有了手册他就能稳定输出而且团队里每个人都能共享同一套最佳实践。agent-skills要解决的核心问题就是这个把“怎么让AI代理把一件事做对”这件事从一次性的提示词prompt里抽出来变成可版本化、可组合、可测试的资产。它通常包含一个skills CLI用来创建、安装、列出、运行技能技能本身往往以目录或包的形式存在里面装着指令、脚本、模板、测试用例。配合Claude Code这类支持工具调用和终端执行的代理运行时技能就能真正落地——代理不只是“聊”而是能读文件、跑命令、改代码、跑测试。这篇文章适合谁看三类人第一类是把Claude Code当日常编码搭子、但总觉得它“时灵时不灵”的开发者第二类是团队里想统一AI编码规范、避免每个人各写一套提示词的技术负责人第三类是对test-driven-development和代理工程化感兴趣、想看看“技能”这层抽象到底怎么设计的工程师。我会从设计思路、核心细节、实操流程、问题排查四个层面把agent-skills这类项目拆开讲透中间会穿插Claude Code的安装配置、skills CLI的用法、以及我在实际使用中踩过的坑。先给一个整体判断agent-skills不是那种“装完就起飞”的银弹它更像是一套工程约束。你投入多少它回报多少。如果你只是偶尔让AI写个正则那没必要上技能体系但如果你每天都要让代理做重复性任务——比如“新增一个API端点并补测试”“按规范重构某个模块”“生成数据库迁移脚本”——那技能包带来的稳定性提升是肉眼可见的。2. 核心设计思路拆解技能为什么比提示词更靠谱2.1 提示词的三个致命伤在讲agent-skills的设计之前得先说清楚它要替代的东西——裸提示词——到底哪里不行。我用Claude Code做项目时最开始也是把要求写在对话里“帮我加一个用户注册接口用FastAPI要校验邮箱写单元测试。”第一次效果不错第二次换个模块代理就开始自由发挥有时候用Pydantic v1的写法有时候忘了加异常处理测试覆盖率忽高忽低。问题出在三个地方。第一是不可复用。提示词躺在聊天记录里换一个会话就没了。你没法像代码一样git clone一份提示词给同事。第二是不可测试。你怎么知道这次代理执行得对只能靠人肉review而人肉review的注意力是有限的。第三是上下文漂移。长对话里代理会逐渐“忘记”早期约束尤其是当你在中间插入了别的任务之后。这三个问题叠加导致裸提示词只适合一次性、低风险的任务。agent-skills的思路是把技能做成文件系统里的实体。一个技能通常是一个目录里面有SKILL.md或类似的主指令文件、可选的脚本、模板、测试。代理运行时比如Claude Code在需要时加载这个技能把里面的指令注入上下文并可以调用技能附带的脚本。这样做的好处是技能可以被版本控制、被代码审查、被自动化测试而且每次加载都是“新鲜”的不会受长对话污染。2.2 技能的分层指令、工具、验收我观察下来一个设计良好的技能包通常分三层。最上层是指令层用自然语言写清楚“什么时候用这个技能、目标是什么、有哪些约束”。这一层是给代理的“大脑”看的要写得像给新人的任务说明而不是像API文档。中间层是工具层也就是技能附带的脚本或命令。比如一个“生成数据库迁移”的技能可能带一个scripts/check_schema.py代理在动手前先跑一下确认当前schema状态。最下层是验收层通常是测试用例或检查清单。test-driven-development之所以常和agent-skills一起出现就是因为TDD天然适合做验收层先写测试代理改代码直到测试通过通过与否是客观的不依赖人的主观判断。这三层对应到skills CLI的操作大概是skills create生成骨架skills install把技能装到代理能发现的位置skills run触发一次技能执行skills test跑验收。不同项目的CLI命令名可能略有差异但逻辑大同小异。理解了这个分层你再看任何agent-skills实现都能快速定位它哪一层做得好、哪一层偷懒了。2.3 为什么选“技能”而不是“插件”或“工作流”有人会问这不就是插件吗或者用工作流引擎比如某些低代码平台也能做。区别在于代理的自主性。插件通常是确定性的输入A输出B中间没有决策。工作流也是预先编排好的。但AI编码代理的价值恰恰在于它能根据上下文做判断——比如同样是“加接口”在有缓存层的项目里它应该顺手加缓存失效逻辑在没有的项目里就不该加。技能给的是约束下的自由度指令层划定边界和验收标准具体怎么实现由代理在边界内决定。这比死板的工作流更适应真实代码库的多样性又比裸提示词更可控。另一个考量是与现有工具链的兼容。Claude Code本身支持读取项目里的CLAUDE.md之类的文件作为上下文agent-skills可以看作是把这种机制进一步结构化、可分发化。你不需要换掉Claude Code只需要在项目里放一个skills/目录代理就能发现并使用。这种“渐进增强”的路径比要求团队整体迁移到某个新平台要现实得多。3. 核心细节解析与实操要点技能包里到底装什么3.1 技能目录的标准结构我参考过几个不同的agent-skills实现也自己搭过比较通用的目录结构是这样的skills/ add-api-endpoint/ SKILL.md scripts/ check_routes.py templates/ endpoint.py.tmpl test_endpoint.py.tmpl tests/ test_skill.pySKILL.md是入口通常包含几块内容name和description让代理知道这个技能是干嘛的、when_to_use触发条件、instructions具体步骤、verification怎么算完成。scripts/放辅助脚本templates/放代码模板tests/放验收测试。这个结构不是强制的但遵循它能让技能更容易被不同运行时识别。写SKILL.md时有个关键技巧指令要写成“检查点”而不是“教程”。比如不要写“首先打开文件然后找到第10行……”而要写“确认目标模块已有对应的测试文件如果没有先创建接口实现后运行pytest tests/test_target.py必须全绿”。前者假设了固定的代码结构后者适应变化。代理在执行时会自己规划路径你只需要把“什么算对”说清楚。3.2 触发条件的设计别让技能乱触发技能多了之后最大的问题不是“代理不会用”而是“代理用错”。比如你有一个“重构”技能和一个“加功能”技能代理可能在你只想加个小功能时触发重构把代码改得面目全非。所以when_to_use要写得足够具体最好包含反例。我常用的写法是当用户明确要求“新增端点”且目标文件是路由文件时使用。如果用户只是问“这个端点怎么工作”不要使用本技能直接解释即可。这种“正向条件反向排除”的写法能显著降低误触发。另外技能之间最好有优先级或互斥声明。有些skills CLI支持在元数据里写conflicts_with没有的话就在指令里手动写清楚。3.3 脚本与代理的协作边界技能附带的脚本应该做确定性的事代理做判断性的事。举个例子一个“生成迁移脚本”的技能脚本可以负责“读取当前数据库schema并输出JSON”代理负责“根据JSON和用户需求决定加哪些字段”。不要让脚本去猜用户意图也不要让代理去手写正则解析schema——那是脚本的活。这个边界划清楚技能就稳定划不清楚就会出现“脚本输出格式变了代理解析失败”这类问题。实操中我建议脚本遵循两个原则输出结构化JSON优先避免自由文本、幂等跑两次结果一样。代理调用脚本时通常会把stdout拿回来解析结构化输出能减少歧义。幂等则保证代理重试时不会产生副作用。3.4 与Claude Code的集成方式Claude Code作为代理运行时集成agent-skills一般有两种方式。一种是项目级在项目根目录放skills/Claude Code启动时自动扫描。这种方式适合团队共享技能跟着代码库走。另一种是用户级装在用户主目录下所有项目都能用。适合个人常用技能比如“按我的代码风格格式化”。配置时要注意Claude Code的上下文窗口。技能不是越多越好每个技能加载都会占token。我一般把项目级技能控制在5个以内用户级控制在10个以内。如果技能很多可以用skills CLI的list命令看看哪些是活跃的定期清理不用的。另外Claude Code的某些版本对技能目录的命名有要求比如必须是skills而不是.skills装完后最好用skills list确认一下代理能不能发现。4. 实操过程与核心环节实现从零搭一个技能并跑通4.1 环境准备Claude Code安装与基础配置在搭技能之前得先把代理运行时装好。Claude Code的安装方式因平台而异。在macOS或Ubuntu上通常通过包管理器或官方提供的安装脚本。安装完成后第一次运行需要配置模型访问方式。这里有个常见问题Claude Code默认可能要求登录官方账号但很多开发者想用自己的第三方API或本地模型。根据热词里提到的“claude code harness可以不登录用其他模型吗”答案是取决于具体版本和配置方式。有些版本支持通过环境变量指定API端点有些则需要修改配置文件。我自己的做法是先按官方文档完成基础安装确认claude命令能跑起来再考虑替换模型。替换模型时注意Claude Code对模型的能力有要求——它需要模型支持工具调用function calling和较长的上下文。如果用一个不支持工具调用的模型代理就无法执行终端命令技能里的脚本也就跑不起来。所以选模型时先确认它支持这些能力。配置完成后用claude --version和claude 列出当前目录文件做个冒烟测试确认代理能读文件、能执行命令。4.2 用skills CLI创建第一个技能假设skills CLI已经装好通常通过npm或pip创建技能的命令大概是skills create add-api-endpoint --template basic这会生成一个技能目录骨架。然后编辑SKILL.md填入指令。我以一个FastAPI项目为例写一个“新增GET端点”的技能。指令部分我会这样写## 目标 在指定的路由文件中新增一个GET端点返回JSON并补充对应的单元测试。 ## 步骤 1. 确认目标路由文件存在且已导入必要的依赖如 APIRouter。 2. 在路由文件中新增端点函数路径和函数名由用户指定。 3. 在 tests/ 下找到或创建对应的测试文件新增测试用例覆盖正常返回和参数校验失败两种情况。 4. 运行 pytest tests/确保新增测试通过且没有破坏已有测试。 ## 验收 - 新端点可通过 curl 或测试客户端访问。 - 新增测试全部通过。 - 已有测试无回归。写完后用skills install add-api-endpoint把它装到项目里。然后启动Claude Code输入“用add-api-endpoint技能在users路由里加一个GET /users/{id}端点”。代理应该会加载技能、按步骤执行、最后跑测试。4.3 参数计算与选择技能粒度的权衡技能粒度是个需要反复调的参数。太粗比如一个“开发整个功能”的技能指令会变得又长又模糊代理执行时容易跑偏太细比如“新增一行import”也做成技能技能数量爆炸维护成本高。我的经验是一个技能对应一个可独立验收的交付物。比如“新增端点”是一个交付物“新增数据库迁移”是另一个“重构某个函数”是第三个。每个交付物都有明确的完成标准这样技能边界清晰验收也简单。另一个参数是指令长度。我试过写很详细的指令结果代理反而拘谨遇到指令没覆盖的情况就卡住。后来我把指令控制在200-400字只写目标、关键约束、验收标准具体实现留给代理。这样代理的完成率反而更高。如果某个技能经常在某个环节出错再针对性地加一条约束而不是一开始就写满。4.4 跑通TDD闭环让测试成为技能的裁判test-driven-development和agent-skills结合效果最好。具体做法是技能指令里明确要求“先写测试再写实现最后跑测试”。代理执行时会先根据模板生成测试文件然后实现功能再运行测试。如果测试失败代理会根据错误信息调整实现直到通过。这个闭环的关键是测试必须由技能提供或由代理生成且可运行。如果测试是写在指令里的伪代码代理没法执行闭环就断了。我在实操中会要求技能附带一个tests/目录里面放一个基础测试模板。代理生成新测试时基于模板改保证测试框架和项目一致。跑测试的命令也写在技能里比如pytest tests/test_users.py -v。这样代理不需要猜项目用什么测试框架。实测下来有TDD闭环的技能一次通过率比没有的高不少因为代理有了客观的反馈信号不会“自认为写对了”就停下。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误最常见的问题是代理根本没加载技能。排查步骤先用skills list确认技能已安装且路径正确然后检查Claude Code的启动日志看它扫描了哪些目录最后确认技能名和用户输入的关键词是否匹配。如果技能被加载了但没触发多半是when_to_use写得太窄或太宽。太窄就放宽条件太宽就加反例。我遇到过一次技能描述里写了“新增端点”结果用户说“加个接口”就没触发。后来在描述里补了“接口、端点、路由”几个同义词问题解决。5.2 脚本执行失败脚本失败通常有三类原因路径问题、依赖问题、权限问题。路径问题最常见——脚本里用了相对路径但代理的工作目录和预期不一致。解决办法是在脚本里用绝对路径或者让技能指令明确cd到项目根目录再执行。依赖问题比如脚本需要requests但环境里没装解决办法是在技能里声明依赖或者把脚本写成只用标准库。权限问题在Ubuntu上常见脚本没有执行权限chmod x即可。排查时先手动跑一遍脚本确认脚本本身没问题再看代理调用时的上下文差异。5.3 代理“自作主张”偏离技能有时候代理加载了技能但执行到一半开始自由发挥比如跳过了测试步骤。这通常是因为指令里的验收标准不够硬。我的对策是把验收标准写成可执行的检查而不是描述性文字。比如不写“确保测试通过”而写“运行pytest tests/ -q退出码必须为0”。代理对可执行检查的遵守度明显更高。另外可以在技能里加一条“如果任何验收检查失败停止并报告不要继续修改代码”防止代理在失败后乱改。5.4 技能之间的冲突当项目里有多个技能时可能出现两个技能都声称适用的情况。比如“新增端点”和“重构路由”都匹配“修改路由文件”。解决办法是在技能元数据里声明优先级或者在指令里写清楚互斥条件。我一般会给技能加一个priority字段数字小的优先。如果没有这个机制就在SKILL.md开头写“本技能仅当用户明确要求新增功能时使用如果用户要求改善现有代码结构请使用重构技能”。5.5 常见问题速查表问题现象可能原因排查动作解决方式技能完全不触发未安装或路径错误skills list检查重新安装确认目录名触发但执行偏离指令验收标准模糊检查SKILL.md改为可执行检查脚本报路径错误工作目录不一致手动跑脚本对比脚本内用绝对路径测试跑不起来测试框架不匹配检查项目依赖技能内声明框架和命令多个技能冲突触发条件重叠查看技能描述加优先级或互斥声明代理中途停止上下文超限查看token用量精简技能拆分任务5.6 几个我踩过的坑第一个坑是技能名用中文。早期我图省事技能名写成“新增接口”结果CLI和代理对中文名的处理不一致有时找不到。后来统一用英文短横线命名问题消失。第二个坑是在技能里写死项目路径。换一个项目技能就废了。正确做法是用相对路径或环境变量。第三个坑是技能太多导致启动慢。Claude Code启动时要扫描所有技能技能多了启动明显变慢。定期清理不用的技能能省不少时间。第四个坑是忽略代理的反馈。有时候代理会报告“技能里的某条指令与当前代码库不符”这其实是技能需要更新的信号别忽略及时改。6. 技能体系的扩展与团队协作6.1 把技能纳入代码审查技能既然是文件就应该像代码一样审查。我们团队的做法是新增或修改技能时走正常的PR流程至少一个人review。review的重点不是指令写得好不好看而是验收标准是否可执行、触发条件是否清晰、有没有和现有技能冲突。review通过后技能随代码库一起合并所有人下次拉代码就能用。这样技能的质量有保障也不会出现“某个人本地有个神奇技能但别人都没有”的情况。6.2 技能的分发与版本管理技能可以放在项目仓库里也可以做成独立的包通过skills CLI分发。项目级技能适合和项目强相关的比如“按本项目规范生成迁移”。跨项目通用的技能比如“生成commit message”适合做成包。版本管理上技能包遵循语义化版本代理加载时检查版本兼容性。如果技能依赖某个特定版本的Claude Code或某个脚本运行时在元数据里声明避免不兼容导致执行失败。6.3 用技能沉淀团队最佳实践技能最大的价值我觉得是把团队里“老手才知道的坑”固化下来。比如我们项目里有个约定所有数据库查询必须走一个封装层不能直接调ORM。这个约定以前只存在于文档和口口相传中新人经常忘。后来我把它写进“新增查询”技能的指令里代理每次生成查询代码都会自动走封装层。新人用代理时自然就遵循了规范。这比写十页文档都管用。所以我的建议是每当你发现自己在重复提醒代理某件事就把它做成技能。6.4 技能与测试驱动开发的深度结合最后再展开说一下TDD。agent-skills加TDD本质上是在给代理建立反馈回路。没有反馈回路代理只能靠“感觉”判断自己做对了没有这在复杂任务上极不可靠。有了测试代理每改一次代码就能得到客观信号。我现在的做法是技能指令里强制要求“先运行测试确认失败再实现再运行测试确认通过”。这个“红-绿”循环代理执行起来很自然而且能有效防止它跳过验证。实测下来带TDD闭环的技能产出代码的一次通过率能到八成以上不带的话可能只有五成。这个差距在每天几十次调用的场景下累积起来非常可观。如果你刚开始接触agent-skills我的建议是从一个小技能做起比如“新增一个简单的工具函数并补测试”。跑通整个流程后再逐步扩展。别一上来就搞大而全的技能体系那样容易在细节里迷失。技能这东西用起来才知道哪里需要调整先跑起来比什么都重要。