1. 从“agent-skills”说起为什么AI编码代理需要一套技能体系“agent-skills”这个词最近在AI编码代理的圈子里被反复提及但很多人第一次看到它时并不清楚它到底指什么。简单来说agent-skills是一套面向AI编码代理的技能定义与组织规范它把“让AI代理完成某类编码任务”所需的知识、流程、约束和验证手段打包成可复用、可组合、可版本管理的技能单元。你可以把它理解成给AI代理准备的“岗位操作手册”——不是一份泛泛的提示词而是包含触发条件、执行步骤、工具调用约定、验收标准的完整工作包。这件事为什么值得单独拿出来讲因为过去一年里AI编码代理的能力提升非常快从最初的代码补全到能读仓库、改文件、跑测试、提交变更代理能做的事情越来越多。但随之而来的问题是能力越强越需要约束和结构。一个没有技能体系的代理就像一个什么工具都往手里塞的新人你让它改一个bug它可能顺手重构了三个模块还改动了配置文件。agent-skills要解决的核心问题就是让代理的行为变得可预期、可复用、可审查。这套东西适合谁来了解如果你只是偶尔用AI写几行代码可能暂时用不上但如果你在团队里推动AI编码代理落地或者你自己在搭建基于代理的自动化开发流程agent-skills就是绕不开的基础设施。它和Claude Code、skills CLI、test-driven-development这些热词紧密相关因为这些正是技能体系落地时最常打交道的工具和方法论。我自己的体会是agent-skills的价值不在于“让AI更聪明”而在于“让AI更可控”。聪明是模型本身的事可控才是工程化的事。下面我会从设计思路、核心细节、实操过程、问题排查几个层面把这套东西拆开讲清楚。2. 整体设计与思路拆解技能单元为什么这样切分2.1 技能的定义边界一个技能只做一件事agent-skills最核心的设计原则是单一职责。一个技能只负责一类任务比如“修复失败的单元测试”“为指定函数补充类型注解”“按规范生成数据库迁移脚本”。这个边界看起来简单但实际切分时非常容易走偏。我见过不少人把技能写成“帮我优化这个项目”这种技能定义太宽代理执行时只能靠猜结果就是每次行为都不一样。正确的做法是把任务拆到“输入明确、输出可验证”的粒度。举个例子“修复失败的单元测试”这个技能输入是测试运行结果和失败用例输出是修改后的代码和重新运行的测试结果中间步骤包括定位失败原因、修改实现或测试、重新执行验证。每一步都有明确的判断依据代理不需要自由发挥。为什么单一职责这么重要因为代理的执行过程本质上是在不确定中寻找确定。技能边界越清晰代理需要做的决策就越少行为就越稳定。这和微服务拆分的逻辑类似服务越小职责越单一整体系统的可预测性就越高。2.2 技能与提示词的区别从“说清楚”到“可执行”很多人会把agent-skills和提示词工程混为一谈觉得不就是写一段更详细的指令吗。这两者的区别在于提示词解决的是“说清楚”技能解决的是“可执行”。一段好的提示词可以告诉代理“你要先读测试文件再改实现”但技能会进一步规定读测试文件时用哪个工具、改实现时遵循什么代码规范、改完之后必须运行哪条命令验证、验证失败时最多重试几次、重试仍失败时如何上报。这些内容不是靠自然语言描述而是通过结构化的技能定义来约束。我自己的经验是提示词是给模型看的技能是给系统用的。提示词可以灵活调整技能需要版本管理。当你在团队里推广AI编码代理时技能文件应该像代码一样进仓库、走评审、有变更记录。这样才能保证不同人、不同时间使用代理时行为是一致的。2.3 技能组合与编排为什么需要skills CLI单个技能能做的事情有限真正有价值的是技能的组合。比如“修复失败的单元测试”这个技能内部可能调用了“读取文件”“运行命令”“修改代码”三个基础技能。这种组合关系需要一套机制来管理skills CLI就是干这个的。skills CLI提供的能力包括列出可用技能、查看技能详情、安装技能到指定项目、组合多个技能形成工作流、校验技能定义的合法性。它的作用类似于包管理器只不过管理的是技能而不是依赖库。为什么需要CLI而不是纯配置文件因为技能的使用场景是动态的你可能需要在不同项目里启用不同技能组合CLI提供了更灵活的操作方式。从设计角度看skills CLI把技能的“定义”和“使用”分开了。技能定义是静态的、可版本管理的技能使用是动态的、按需组合的。这种分离让技能体系既能保持稳定又能适应不同项目的需求。2.4 与test-driven-development的天然契合agent-skills和test-driven-developmentTDD的结合非常自然因为TDD本身就提供了清晰的验证闭环。在TDD流程里先写测试、再写实现、最后重构每一步都有明确的输入输出。这正好符合技能定义的要求。我实际用下来发现以TDD为骨架的技能最容易写也最稳定。因为测试本身就是验收标准代理不需要额外判断“做完了没有”跑一遍测试就知道。相比之下那些没有明确验证手段的技能比如“优化代码可读性”就很难定义什么叫“做完了”代理容易陷入无限修改。所以如果你刚开始搭建技能体系我建议从TDD相关的技能入手。先把“根据需求写测试”“根据测试写实现”“重构并保持测试通过”这几个技能做扎实再扩展到其他类型。3. 核心细节解析与实操要点技能文件到底怎么写3.1 技能文件的基本结构一个标准的技能定义通常包含以下几个部分元信息、触发条件、输入参数、执行步骤、工具约定、验证方式、失败处理。我用一个实际例子来说明假设我们要定义一个“修复失败的单元测试”技能。元信息部分包括技能名称、版本、作者、描述。这部分看起来简单但版本管理很重要因为技能会迭代不同版本的行为可能不同。触发条件描述什么情况下应该使用这个技能比如“当测试运行结果中存在失败用例时”。输入参数定义技能需要哪些信息比如测试命令、失败用例列表、代码仓库路径。执行步骤是核心部分需要把代理的操作拆成有序的步骤。每一步都要说明做什么、用什么工具、预期结果是什么。工具约定部分规定代理可以调用哪些工具比如文件读写、命令执行、代码搜索。验证方式说明如何判断技能执行成功通常是重新运行测试并检查结果。失败处理定义当验证不通过时该怎么办比如重试、回滚、上报。3.2 触发条件的写法避免误触发和漏触发触发条件是技能体系里最容易被忽视的部分但它直接决定了技能会不会在正确的时机被调用。写得太宽技能会被频繁误触发写得太窄该用的时候用不上。我的经验是触发条件要基于可观测的信号而不是基于意图。比如“当用户表示代码有问题时”这种触发条件就太模糊因为“表示有问题”很难被系统识别。更好的写法是“当测试命令返回非零退出码且输出中包含失败用例信息时”。这个条件基于具体的命令输出系统可以直接判断。另外触发条件之间要有优先级。多个技能可能同时满足触发条件这时候需要一套优先级规则来决定用哪个。通常来说越具体的技能优先级越高。比如“修复特定类型的测试失败”比“修复任意测试失败”更具体应该优先触发。3.3 执行步骤的粒度控制太粗和太细都不行执行步骤的粒度是个需要反复调试的事情。步骤太粗代理的自由度太大行为不稳定步骤太细技能文件会变得冗长维护成本高。我试过几种粒度最后发现按“可独立验证的操作”来切分比较合适。什么意思就是每一步做完之后都能有一个明确的判断依据来说明这一步是否成功。比如“读取失败测试文件”这一步判断依据是文件内容成功返回“定位失败断言”这一步判断依据是找到了具体的断言位置“修改实现代码”这一步判断依据是代码变更成功写入。如果某一步做完之后无法判断是否成功说明这一步还需要继续拆分。比如“修复代码逻辑”就无法独立验证需要拆成“定位问题代码”“修改代码”“运行相关测试”几个步骤。3.4 工具约定的边界代理能做什么不能做什么工具约定是技能体系的安全边界。代理能调用哪些工具、能访问哪些资源、能执行哪些命令都需要在技能定义里明确。这不是限制代理的能力而是保证代理的行为在可控范围内。我通常会把工具分成几类只读工具读文件、搜索代码、查看命令输出、写入工具修改文件、创建文件、执行工具运行测试、运行构建。对于修复类技能只读工具可以自由使用写入工具需要谨慎执行工具要限定范围。比如运行测试命令是允许的但运行部署命令就不应该在这个技能里出现。注意工具约定不是越严越好。限制太多会导致技能无法完成基本任务限制太少又失去控制。我的做法是先放开观察代理的实际行为再把不必要的工具权限收掉。3.5 验证方式的设计怎么判断技能执行成功验证方式是技能体系的闭环。没有验证技能执行完就结束了你根本不知道做对了没有。验证方式的设计要遵循一个原则验证结果必须是客观的、可重复的。对于编码类技能最直接的验证方式就是运行测试。测试通过就是成功测试失败就是失败没有歧义。如果技能不涉及代码变更比如“生成项目文档”验证方式可以是检查输出文件是否存在、格式是否符合预期。有些技能的验证比较间接比如“优化代码结构”。这种情况下可以设计多级验证第一级检查代码是否能编译通过第二级检查测试是否仍然通过第三级检查代码复杂度指标是否改善。每一级都是客观的组合起来就能较好地判断技能效果。3.6 失败处理的策略重试、回滚还是上报失败处理是技能体系里最体现代价的部分。代理执行技能不可能每次都成功失败之后怎么办直接决定了技能是否可用。常见的失败处理策略有三种重试、回滚、上报。重试适用于临时性失败比如网络抖动导致的命令超时。回滚适用于产生了副作用但验证失败的场景比如修改了代码但测试没通过需要把代码恢复到修改前。上报适用于无法自动处理的失败比如技能定义本身有问题或者遇到了预期之外的情况。我的建议是默认采用“回滚上报”策略。重试虽然看起来简单但容易掩盖问题。如果失败是系统性的重试多少次都没用反而浪费资源。回滚保证不会留下烂摊子上报让人类介入判断。只有在明确知道失败是临时性的情况下才启用重试。4. 实操过程与核心环节实现从零搭建一个技能4.1 环境准备Claude Code与skills CLI的安装配置要实操agent-skills首先需要一套支持技能体系的AI编码代理环境。目前比较常用的组合是Claude Code加上skills CLI。Claude Code提供了代理的基础能力包括文件操作、命令执行、代码理解skills CLI提供了技能的管理和编排能力。安装Claude Code的过程根据操作系统有所不同。在macOS上通常通过包管理器安装在Ubuntu上需要先确认系统依赖是否齐全再执行安装命令。安装完成后需要配置API访问方式。这里要注意不同地区的可用性可能不同需要确认所在区域是否在支持范围内。skills CLI的安装相对简单通常通过npm或类似的包管理工具安装。安装完成后可以用skills list命令查看当前可用的技能用skills install命令安装新技能。我建议先把官方提供的基础技能装上一批熟悉一下技能文件的结构再尝试自己写。提示环境配置阶段最容易出问题的是权限和路径。确保代理有权限读取项目文件、执行测试命令同时确保技能文件的存放路径在代理的搜索范围内。4.2 第一个技能根据测试失败信息修复实现代码我们从最实用的技能开始根据测试失败信息修复实现代码。这个技能的输入是测试命令和失败输出输出是修改后的代码和重新运行的测试结果。技能定义的核心步骤是这样的第一步运行测试命令并捕获输出第二步解析输出提取失败用例的名称、断言位置和期望值与实际值的差异第三步读取相关实现代码第四步根据失败信息定位问题原因第五步修改实现代码第六步重新运行测试验证第七步如果测试通过则结束如果失败则回滚并上报。这里的关键点是第二步的解析。测试输出格式多种多样有JUnit风格的、有pytest风格的、有Go test风格的。技能定义里需要说明支持哪些格式遇到不支持的格式怎么处理。我的做法是先支持项目里最常用的测试框架其他格式后续再扩展。第四步的定位问题原因是最考验代理能力的环节。代理需要理解测试期望什么、实现实际做了什么、差异在哪里。这一步很难用固定规则描述通常需要给代理一些启发式指导比如“优先检查边界条件”“优先检查类型转换”“优先检查空值处理”。4.3 参数计算与选择重试次数和超时时间怎么定技能执行过程中涉及一些参数比如重试次数、超时时间、最大修改行数。这些参数不能拍脑袋定需要根据实际情况计算。重试次数的计算逻辑是假设单次执行成功率为p希望整体成功率达到P那么重试次数n满足1-(1-p)^n ≥ P。比如单次成功率0.6希望整体达到0.95那么n至少为3。但这是理论值实际还要考虑重试的成本。如果每次重试都要跑一遍完整测试耗时很长那重试次数就不宜太多。超时时间的计算逻辑是统计正常情况下技能执行的平均耗时和最大耗时超时时间设为最大耗时的1.5到2倍。比如正常执行平均30秒最大60秒超时时间可以设为90到120秒。这样既能容纳正常的波动又不会让代理无限等待。最大修改行数是为了防止代理过度修改。我的经验值是单次技能执行修改不超过50行代码。超过这个数说明问题可能比较复杂应该拆成多个技能或者人工介入。4.4 实操现场记录一次完整的技能执行过程我拿一个实际项目来演示。项目是一个Node.js的API服务有一个测试用例失败了报错信息显示期望返回200但实际返回500。代理首先运行测试命令捕获到失败输出。然后解析输出提取出失败用例的名称是“GET /users should return 200”断言位置在users.test.js第42行期望值是200实际值是500。接着代理读取users.test.js第42行附近的代码看到测试逻辑是发起GET请求并检查状态码。然后代理读取对应的路由处理代码发现是users.js里的getUsers函数。代理进一步读取该函数发现它在查询数据库时没有处理连接失败的情况直接抛出了异常导致返回500。代理修改代码在数据库查询外面加了try-catch连接失败时返回503而不是抛出异常。然后重新运行测试这次测试通过了。代理记录下修改内容和验证结果技能执行结束。整个过程耗时约45秒修改了8行代码。这个案例说明技能执行的关键在于逐步缩小问题范围从测试失败到具体断言从断言到实现代码从实现代码到具体问题。每一步都有明确的依据不是靠猜。4.5 技能文件的版本管理与团队协作技能文件写完之后需要纳入版本管理。我通常把技能文件放在项目的.skills目录下和代码一起提交。这样不同分支可以有不同的技能版本合并时也能看到技能变更。团队协作时技能文件的评审和代码评审一样重要。评审时要关注触发条件是否准确、执行步骤是否完整、工具约定是否合理、验证方式是否可靠、失败处理是否妥当。特别是工具约定要确保没有开放不必要的权限。另外技能文件要有变更记录。每次修改都要说明改了什么、为什么改、影响范围是什么。这样当技能行为发生变化时可以追溯到具体原因。5. 常见问题与排查技巧实录5.1 技能不触发或误触发怎么办技能不触发通常是因为触发条件写得太窄。比如只匹配了特定格式的测试输出换一个测试框架就不认了。解决办法是把触发条件放宽到基于通用信号比如“命令退出码非零”而不是“输出中包含特定字符串”。技能误触发通常是因为触发条件写得太宽。比如“当代码有变更时”这个条件几乎任何时候都成立导致技能被频繁调用。解决办法是增加更多约束条件比如“当代码有变更且测试失败时”。排查这类问题的技巧是先看代理的决策日志确认它在每个时刻判断了哪些触发条件、结果是什么。然后对照技能定义找出判断逻辑和预期不一致的地方。5.2 技能执行到一半卡住了怎么排查技能执行卡住通常有几个原因命令执行超时、工具调用失败、代理陷入循环。排查时先看当前执行到哪一步然后检查这一步涉及的工具和命令。如果是命令执行超时检查命令本身是否正常以及超时时间设置是否合理。如果是工具调用失败检查工具权限和参数是否正确。如果是代理陷入循环检查执行步骤是否有明确的退出条件。我遇到过一次代理在“修改代码-运行测试-修改代码”之间循环了十几次。原因是测试失败信息不够明确代理每次修改都只改一点点始终无法通过。解决办法是在技能定义里增加“最大修改次数”限制超过就上报。5.3 技能执行结果不稳定怎么处理同一个技能有时候成功有时候失败这种不稳定最让人头疼。常见原因包括测试本身不稳定比如依赖外部服务、代理决策有随机性、环境差异。对于测试不稳定的情况需要先修复测试本身比如增加mock、减少外部依赖。对于代理决策随机性的情况可以通过增加约束来减少自由度比如把“修改实现代码”细化为“在指定函数内修改”。对于环境差异的情况需要确保技能执行环境一致比如统一Node.js版本、统一依赖版本。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能不触发触发条件太窄查看决策日志放宽触发条件技能误触发触发条件太宽查看决策日志增加约束条件执行卡住命令超时/工具失败/循环查看当前步骤调整超时/检查权限/增加退出条件结果不稳定测试不稳定/决策随机/环境差异重复执行对比修复测试/增加约束/统一环境修改过度步骤粒度太粗检查修改行数细化步骤/增加行数限制验证失败后无动作失败处理缺失检查技能定义补充回滚和上报逻辑5.5 几个我踩过的坑第一个坑是技能定义写得太理想化。我一开始把执行步骤写得非常详细每一步都规定了具体操作。结果实际执行时发现代理经常遇到预期之外的情况比如测试文件不存在、代码格式不符合预期。后来我学会了在技能定义里留一些弹性空间允许代理在遇到意外时先尝试简单处理处理不了再上报。第二个坑是忽视技能之间的依赖关系。有些技能需要其他技能先执行比如“修复测试失败”需要“运行测试”先执行。如果依赖关系没定义清楚代理可能会跳过前置步骤直接执行后续技能导致失败。解决办法是在技能定义里明确前置条件和后置条件。第三个坑是验证方式过于宽松。我一开始只检查测试是否通过后来发现有些修改虽然让测试通过了但引入了新的问题比如性能下降、代码风格不一致。后来我在验证方式里增加了代码风格检查和性能基线检查确保修改是全面的。第四个坑是没有考虑技能执行的成本。有些技能执行一次要跑完整测试套件耗时很长。如果频繁触发会严重影响开发效率。后来我给技能增加了执行频率限制比如同一个技能在短时间内不重复执行。6. 技能体系的扩展与长期维护6.1 从单个技能到技能库当你写了几个技能之后会发现它们之间有很多共性。比如多个技能都需要“读取文件”“运行命令”“解析输出”。这时候可以把共性部分抽出来形成基础技能库其他技能基于基础技能组合而成。基础技能库的设计原则是稳定、通用、无副作用。稳定意味着接口不轻易变通用意味着不依赖特定项目无副作用意味着只读不写。这样的基础技能可以被大量上层技能复用减少重复定义。上层技能则专注于业务逻辑比如“修复特定类型的测试失败”“按规范生成API文档”。上层技能可以依赖基础技能但基础技能不应该依赖上层技能。这种分层结构让技能体系更容易维护和扩展。6.2 技能的质量评估与持续改进技能写完之后不是就完了需要持续评估和改进。我通常从几个维度评估技能质量触发准确率、执行成功率、平均执行时间、修改代码量、人工介入频率。触发准确率衡量技能是否在正确的时机被调用。执行成功率衡量技能能否完成任务。平均执行时间衡量技能效率。修改代码量衡量技能是否过度修改。人工介入频率衡量技能是否真正自动化。这些指标可以通过日志统计得到。定期回顾这些指标找出表现不好的技能分析原因并改进。比如某个技能执行成功率低可能是步骤设计有问题某个技能人工介入频率高可能是失败处理不完善。6.3 技能体系与团队工作流的融合技能体系最终要融入团队的工作流。我的做法是把技能执行作为CI/CD流程的一部分。比如在代码提交后自动运行测试如果测试失败自动触发“修复测试失败”技能。如果技能修复成功自动提交修复如果修复失败通知开发者介入。这种融合的关键是明确技能的边界和人的边界。技能负责处理明确、重复、可验证的任务人负责处理模糊、复杂、需要判断的任务。两者配合才能发挥最大效果。另外技能体系需要和代码评审流程结合。技能修改的代码同样需要评审不能因为“是AI改的”就跳过评审。评审时重点关注修改是否符合预期、是否引入了新问题、是否遵循了代码规范。6.4 后续可以扩展的方向技能体系搭建起来之后有几个方向可以继续扩展。一是增加更多类型的技能比如代码审查、性能优化、安全扫描。二是提升技能的智能化程度比如让技能能够根据历史执行记录自动调整参数。三是把技能体系开放给团队让每个人都能贡献技能形成共享的技能库。我自己的计划是先把手头的几个核心技能做扎实确保稳定可靠然后再逐步扩展。技能体系的价值在于用起来而不是在于写得多。一个稳定可靠的技能比十个半成品技能更有价值。最后分享一个小技巧写技能定义时先用手动方式执行一遍任务把每一步的操作和判断都记录下来然后再把这些记录整理成技能定义。这样写出来的技能最贴近实际也最容易验证。我试过直接凭想象写技能定义结果执行时发现很多步骤在实际中根本行不通。手动执行一遍再写效率高很多。 AI编码代理技能体系agent-skills：从设计到实操的完整指南
1. 从“agent-skills”说起为什么AI编码代理需要一套技能体系“agent-skills”这个词最近在AI编码代理的圈子里被反复提及但很多人第一次看到它时并不清楚它到底指什么。简单来说agent-skills是一套面向AI编码代理的技能定义与组织规范它把“让AI代理完成某类编码任务”所需的知识、流程、约束和验证手段打包成可复用、可组合、可版本管理的技能单元。你可以把它理解成给AI代理准备的“岗位操作手册”——不是一份泛泛的提示词而是包含触发条件、执行步骤、工具调用约定、验收标准的完整工作包。这件事为什么值得单独拿出来讲因为过去一年里AI编码代理的能力提升非常快从最初的代码补全到能读仓库、改文件、跑测试、提交变更代理能做的事情越来越多。但随之而来的问题是能力越强越需要约束和结构。一个没有技能体系的代理就像一个什么工具都往手里塞的新人你让它改一个bug它可能顺手重构了三个模块还改动了配置文件。agent-skills要解决的核心问题就是让代理的行为变得可预期、可复用、可审查。这套东西适合谁来了解如果你只是偶尔用AI写几行代码可能暂时用不上但如果你在团队里推动AI编码代理落地或者你自己在搭建基于代理的自动化开发流程agent-skills就是绕不开的基础设施。它和Claude Code、skills CLI、test-driven-development这些热词紧密相关因为这些正是技能体系落地时最常打交道的工具和方法论。我自己的体会是agent-skills的价值不在于“让AI更聪明”而在于“让AI更可控”。聪明是模型本身的事可控才是工程化的事。下面我会从设计思路、核心细节、实操过程、问题排查几个层面把这套东西拆开讲清楚。2. 整体设计与思路拆解技能单元为什么这样切分2.1 技能的定义边界一个技能只做一件事agent-skills最核心的设计原则是单一职责。一个技能只负责一类任务比如“修复失败的单元测试”“为指定函数补充类型注解”“按规范生成数据库迁移脚本”。这个边界看起来简单但实际切分时非常容易走偏。我见过不少人把技能写成“帮我优化这个项目”这种技能定义太宽代理执行时只能靠猜结果就是每次行为都不一样。正确的做法是把任务拆到“输入明确、输出可验证”的粒度。举个例子“修复失败的单元测试”这个技能输入是测试运行结果和失败用例输出是修改后的代码和重新运行的测试结果中间步骤包括定位失败原因、修改实现或测试、重新执行验证。每一步都有明确的判断依据代理不需要自由发挥。为什么单一职责这么重要因为代理的执行过程本质上是在不确定中寻找确定。技能边界越清晰代理需要做的决策就越少行为就越稳定。这和微服务拆分的逻辑类似服务越小职责越单一整体系统的可预测性就越高。2.2 技能与提示词的区别从“说清楚”到“可执行”很多人会把agent-skills和提示词工程混为一谈觉得不就是写一段更详细的指令吗。这两者的区别在于提示词解决的是“说清楚”技能解决的是“可执行”。一段好的提示词可以告诉代理“你要先读测试文件再改实现”但技能会进一步规定读测试文件时用哪个工具、改实现时遵循什么代码规范、改完之后必须运行哪条命令验证、验证失败时最多重试几次、重试仍失败时如何上报。这些内容不是靠自然语言描述而是通过结构化的技能定义来约束。我自己的经验是提示词是给模型看的技能是给系统用的。提示词可以灵活调整技能需要版本管理。当你在团队里推广AI编码代理时技能文件应该像代码一样进仓库、走评审、有变更记录。这样才能保证不同人、不同时间使用代理时行为是一致的。2.3 技能组合与编排为什么需要skills CLI单个技能能做的事情有限真正有价值的是技能的组合。比如“修复失败的单元测试”这个技能内部可能调用了“读取文件”“运行命令”“修改代码”三个基础技能。这种组合关系需要一套机制来管理skills CLI就是干这个的。skills CLI提供的能力包括列出可用技能、查看技能详情、安装技能到指定项目、组合多个技能形成工作流、校验技能定义的合法性。它的作用类似于包管理器只不过管理的是技能而不是依赖库。为什么需要CLI而不是纯配置文件因为技能的使用场景是动态的你可能需要在不同项目里启用不同技能组合CLI提供了更灵活的操作方式。从设计角度看skills CLI把技能的“定义”和“使用”分开了。技能定义是静态的、可版本管理的技能使用是动态的、按需组合的。这种分离让技能体系既能保持稳定又能适应不同项目的需求。2.4 与test-driven-development的天然契合agent-skills和test-driven-developmentTDD的结合非常自然因为TDD本身就提供了清晰的验证闭环。在TDD流程里先写测试、再写实现、最后重构每一步都有明确的输入输出。这正好符合技能定义的要求。我实际用下来发现以TDD为骨架的技能最容易写也最稳定。因为测试本身就是验收标准代理不需要额外判断“做完了没有”跑一遍测试就知道。相比之下那些没有明确验证手段的技能比如“优化代码可读性”就很难定义什么叫“做完了”代理容易陷入无限修改。所以如果你刚开始搭建技能体系我建议从TDD相关的技能入手。先把“根据需求写测试”“根据测试写实现”“重构并保持测试通过”这几个技能做扎实再扩展到其他类型。3. 核心细节解析与实操要点技能文件到底怎么写3.1 技能文件的基本结构一个标准的技能定义通常包含以下几个部分元信息、触发条件、输入参数、执行步骤、工具约定、验证方式、失败处理。我用一个实际例子来说明假设我们要定义一个“修复失败的单元测试”技能。元信息部分包括技能名称、版本、作者、描述。这部分看起来简单但版本管理很重要因为技能会迭代不同版本的行为可能不同。触发条件描述什么情况下应该使用这个技能比如“当测试运行结果中存在失败用例时”。输入参数定义技能需要哪些信息比如测试命令、失败用例列表、代码仓库路径。执行步骤是核心部分需要把代理的操作拆成有序的步骤。每一步都要说明做什么、用什么工具、预期结果是什么。工具约定部分规定代理可以调用哪些工具比如文件读写、命令执行、代码搜索。验证方式说明如何判断技能执行成功通常是重新运行测试并检查结果。失败处理定义当验证不通过时该怎么办比如重试、回滚、上报。3.2 触发条件的写法避免误触发和漏触发触发条件是技能体系里最容易被忽视的部分但它直接决定了技能会不会在正确的时机被调用。写得太宽技能会被频繁误触发写得太窄该用的时候用不上。我的经验是触发条件要基于可观测的信号而不是基于意图。比如“当用户表示代码有问题时”这种触发条件就太模糊因为“表示有问题”很难被系统识别。更好的写法是“当测试命令返回非零退出码且输出中包含失败用例信息时”。这个条件基于具体的命令输出系统可以直接判断。另外触发条件之间要有优先级。多个技能可能同时满足触发条件这时候需要一套优先级规则来决定用哪个。通常来说越具体的技能优先级越高。比如“修复特定类型的测试失败”比“修复任意测试失败”更具体应该优先触发。3.3 执行步骤的粒度控制太粗和太细都不行执行步骤的粒度是个需要反复调试的事情。步骤太粗代理的自由度太大行为不稳定步骤太细技能文件会变得冗长维护成本高。我试过几种粒度最后发现按“可独立验证的操作”来切分比较合适。什么意思就是每一步做完之后都能有一个明确的判断依据来说明这一步是否成功。比如“读取失败测试文件”这一步判断依据是文件内容成功返回“定位失败断言”这一步判断依据是找到了具体的断言位置“修改实现代码”这一步判断依据是代码变更成功写入。如果某一步做完之后无法判断是否成功说明这一步还需要继续拆分。比如“修复代码逻辑”就无法独立验证需要拆成“定位问题代码”“修改代码”“运行相关测试”几个步骤。3.4 工具约定的边界代理能做什么不能做什么工具约定是技能体系的安全边界。代理能调用哪些工具、能访问哪些资源、能执行哪些命令都需要在技能定义里明确。这不是限制代理的能力而是保证代理的行为在可控范围内。我通常会把工具分成几类只读工具读文件、搜索代码、查看命令输出、写入工具修改文件、创建文件、执行工具运行测试、运行构建。对于修复类技能只读工具可以自由使用写入工具需要谨慎执行工具要限定范围。比如运行测试命令是允许的但运行部署命令就不应该在这个技能里出现。注意工具约定不是越严越好。限制太多会导致技能无法完成基本任务限制太少又失去控制。我的做法是先放开观察代理的实际行为再把不必要的工具权限收掉。3.5 验证方式的设计怎么判断技能执行成功验证方式是技能体系的闭环。没有验证技能执行完就结束了你根本不知道做对了没有。验证方式的设计要遵循一个原则验证结果必须是客观的、可重复的。对于编码类技能最直接的验证方式就是运行测试。测试通过就是成功测试失败就是失败没有歧义。如果技能不涉及代码变更比如“生成项目文档”验证方式可以是检查输出文件是否存在、格式是否符合预期。有些技能的验证比较间接比如“优化代码结构”。这种情况下可以设计多级验证第一级检查代码是否能编译通过第二级检查测试是否仍然通过第三级检查代码复杂度指标是否改善。每一级都是客观的组合起来就能较好地判断技能效果。3.6 失败处理的策略重试、回滚还是上报失败处理是技能体系里最体现代价的部分。代理执行技能不可能每次都成功失败之后怎么办直接决定了技能是否可用。常见的失败处理策略有三种重试、回滚、上报。重试适用于临时性失败比如网络抖动导致的命令超时。回滚适用于产生了副作用但验证失败的场景比如修改了代码但测试没通过需要把代码恢复到修改前。上报适用于无法自动处理的失败比如技能定义本身有问题或者遇到了预期之外的情况。我的建议是默认采用“回滚上报”策略。重试虽然看起来简单但容易掩盖问题。如果失败是系统性的重试多少次都没用反而浪费资源。回滚保证不会留下烂摊子上报让人类介入判断。只有在明确知道失败是临时性的情况下才启用重试。4. 实操过程与核心环节实现从零搭建一个技能4.1 环境准备Claude Code与skills CLI的安装配置要实操agent-skills首先需要一套支持技能体系的AI编码代理环境。目前比较常用的组合是Claude Code加上skills CLI。Claude Code提供了代理的基础能力包括文件操作、命令执行、代码理解skills CLI提供了技能的管理和编排能力。安装Claude Code的过程根据操作系统有所不同。在macOS上通常通过包管理器安装在Ubuntu上需要先确认系统依赖是否齐全再执行安装命令。安装完成后需要配置API访问方式。这里要注意不同地区的可用性可能不同需要确认所在区域是否在支持范围内。skills CLI的安装相对简单通常通过npm或类似的包管理工具安装。安装完成后可以用skills list命令查看当前可用的技能用skills install命令安装新技能。我建议先把官方提供的基础技能装上一批熟悉一下技能文件的结构再尝试自己写。提示环境配置阶段最容易出问题的是权限和路径。确保代理有权限读取项目文件、执行测试命令同时确保技能文件的存放路径在代理的搜索范围内。4.2 第一个技能根据测试失败信息修复实现代码我们从最实用的技能开始根据测试失败信息修复实现代码。这个技能的输入是测试命令和失败输出输出是修改后的代码和重新运行的测试结果。技能定义的核心步骤是这样的第一步运行测试命令并捕获输出第二步解析输出提取失败用例的名称、断言位置和期望值与实际值的差异第三步读取相关实现代码第四步根据失败信息定位问题原因第五步修改实现代码第六步重新运行测试验证第七步如果测试通过则结束如果失败则回滚并上报。这里的关键点是第二步的解析。测试输出格式多种多样有JUnit风格的、有pytest风格的、有Go test风格的。技能定义里需要说明支持哪些格式遇到不支持的格式怎么处理。我的做法是先支持项目里最常用的测试框架其他格式后续再扩展。第四步的定位问题原因是最考验代理能力的环节。代理需要理解测试期望什么、实现实际做了什么、差异在哪里。这一步很难用固定规则描述通常需要给代理一些启发式指导比如“优先检查边界条件”“优先检查类型转换”“优先检查空值处理”。4.3 参数计算与选择重试次数和超时时间怎么定技能执行过程中涉及一些参数比如重试次数、超时时间、最大修改行数。这些参数不能拍脑袋定需要根据实际情况计算。重试次数的计算逻辑是假设单次执行成功率为p希望整体成功率达到P那么重试次数n满足1-(1-p)^n ≥ P。比如单次成功率0.6希望整体达到0.95那么n至少为3。但这是理论值实际还要考虑重试的成本。如果每次重试都要跑一遍完整测试耗时很长那重试次数就不宜太多。超时时间的计算逻辑是统计正常情况下技能执行的平均耗时和最大耗时超时时间设为最大耗时的1.5到2倍。比如正常执行平均30秒最大60秒超时时间可以设为90到120秒。这样既能容纳正常的波动又不会让代理无限等待。最大修改行数是为了防止代理过度修改。我的经验值是单次技能执行修改不超过50行代码。超过这个数说明问题可能比较复杂应该拆成多个技能或者人工介入。4.4 实操现场记录一次完整的技能执行过程我拿一个实际项目来演示。项目是一个Node.js的API服务有一个测试用例失败了报错信息显示期望返回200但实际返回500。代理首先运行测试命令捕获到失败输出。然后解析输出提取出失败用例的名称是“GET /users should return 200”断言位置在users.test.js第42行期望值是200实际值是500。接着代理读取users.test.js第42行附近的代码看到测试逻辑是发起GET请求并检查状态码。然后代理读取对应的路由处理代码发现是users.js里的getUsers函数。代理进一步读取该函数发现它在查询数据库时没有处理连接失败的情况直接抛出了异常导致返回500。代理修改代码在数据库查询外面加了try-catch连接失败时返回503而不是抛出异常。然后重新运行测试这次测试通过了。代理记录下修改内容和验证结果技能执行结束。整个过程耗时约45秒修改了8行代码。这个案例说明技能执行的关键在于逐步缩小问题范围从测试失败到具体断言从断言到实现代码从实现代码到具体问题。每一步都有明确的依据不是靠猜。4.5 技能文件的版本管理与团队协作技能文件写完之后需要纳入版本管理。我通常把技能文件放在项目的.skills目录下和代码一起提交。这样不同分支可以有不同的技能版本合并时也能看到技能变更。团队协作时技能文件的评审和代码评审一样重要。评审时要关注触发条件是否准确、执行步骤是否完整、工具约定是否合理、验证方式是否可靠、失败处理是否妥当。特别是工具约定要确保没有开放不必要的权限。另外技能文件要有变更记录。每次修改都要说明改了什么、为什么改、影响范围是什么。这样当技能行为发生变化时可以追溯到具体原因。5. 常见问题与排查技巧实录5.1 技能不触发或误触发怎么办技能不触发通常是因为触发条件写得太窄。比如只匹配了特定格式的测试输出换一个测试框架就不认了。解决办法是把触发条件放宽到基于通用信号比如“命令退出码非零”而不是“输出中包含特定字符串”。技能误触发通常是因为触发条件写得太宽。比如“当代码有变更时”这个条件几乎任何时候都成立导致技能被频繁调用。解决办法是增加更多约束条件比如“当代码有变更且测试失败时”。排查这类问题的技巧是先看代理的决策日志确认它在每个时刻判断了哪些触发条件、结果是什么。然后对照技能定义找出判断逻辑和预期不一致的地方。5.2 技能执行到一半卡住了怎么排查技能执行卡住通常有几个原因命令执行超时、工具调用失败、代理陷入循环。排查时先看当前执行到哪一步然后检查这一步涉及的工具和命令。如果是命令执行超时检查命令本身是否正常以及超时时间设置是否合理。如果是工具调用失败检查工具权限和参数是否正确。如果是代理陷入循环检查执行步骤是否有明确的退出条件。我遇到过一次代理在“修改代码-运行测试-修改代码”之间循环了十几次。原因是测试失败信息不够明确代理每次修改都只改一点点始终无法通过。解决办法是在技能定义里增加“最大修改次数”限制超过就上报。5.3 技能执行结果不稳定怎么处理同一个技能有时候成功有时候失败这种不稳定最让人头疼。常见原因包括测试本身不稳定比如依赖外部服务、代理决策有随机性、环境差异。对于测试不稳定的情况需要先修复测试本身比如增加mock、减少外部依赖。对于代理决策随机性的情况可以通过增加约束来减少自由度比如把“修改实现代码”细化为“在指定函数内修改”。对于环境差异的情况需要确保技能执行环境一致比如统一Node.js版本、统一依赖版本。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能不触发触发条件太窄查看决策日志放宽触发条件技能误触发触发条件太宽查看决策日志增加约束条件执行卡住命令超时/工具失败/循环查看当前步骤调整超时/检查权限/增加退出条件结果不稳定测试不稳定/决策随机/环境差异重复执行对比修复测试/增加约束/统一环境修改过度步骤粒度太粗检查修改行数细化步骤/增加行数限制验证失败后无动作失败处理缺失检查技能定义补充回滚和上报逻辑5.5 几个我踩过的坑第一个坑是技能定义写得太理想化。我一开始把执行步骤写得非常详细每一步都规定了具体操作。结果实际执行时发现代理经常遇到预期之外的情况比如测试文件不存在、代码格式不符合预期。后来我学会了在技能定义里留一些弹性空间允许代理在遇到意外时先尝试简单处理处理不了再上报。第二个坑是忽视技能之间的依赖关系。有些技能需要其他技能先执行比如“修复测试失败”需要“运行测试”先执行。如果依赖关系没定义清楚代理可能会跳过前置步骤直接执行后续技能导致失败。解决办法是在技能定义里明确前置条件和后置条件。第三个坑是验证方式过于宽松。我一开始只检查测试是否通过后来发现有些修改虽然让测试通过了但引入了新的问题比如性能下降、代码风格不一致。后来我在验证方式里增加了代码风格检查和性能基线检查确保修改是全面的。第四个坑是没有考虑技能执行的成本。有些技能执行一次要跑完整测试套件耗时很长。如果频繁触发会严重影响开发效率。后来我给技能增加了执行频率限制比如同一个技能在短时间内不重复执行。6. 技能体系的扩展与长期维护6.1 从单个技能到技能库当你写了几个技能之后会发现它们之间有很多共性。比如多个技能都需要“读取文件”“运行命令”“解析输出”。这时候可以把共性部分抽出来形成基础技能库其他技能基于基础技能组合而成。基础技能库的设计原则是稳定、通用、无副作用。稳定意味着接口不轻易变通用意味着不依赖特定项目无副作用意味着只读不写。这样的基础技能可以被大量上层技能复用减少重复定义。上层技能则专注于业务逻辑比如“修复特定类型的测试失败”“按规范生成API文档”。上层技能可以依赖基础技能但基础技能不应该依赖上层技能。这种分层结构让技能体系更容易维护和扩展。6.2 技能的质量评估与持续改进技能写完之后不是就完了需要持续评估和改进。我通常从几个维度评估技能质量触发准确率、执行成功率、平均执行时间、修改代码量、人工介入频率。触发准确率衡量技能是否在正确的时机被调用。执行成功率衡量技能能否完成任务。平均执行时间衡量技能效率。修改代码量衡量技能是否过度修改。人工介入频率衡量技能是否真正自动化。这些指标可以通过日志统计得到。定期回顾这些指标找出表现不好的技能分析原因并改进。比如某个技能执行成功率低可能是步骤设计有问题某个技能人工介入频率高可能是失败处理不完善。6.3 技能体系与团队工作流的融合技能体系最终要融入团队的工作流。我的做法是把技能执行作为CI/CD流程的一部分。比如在代码提交后自动运行测试如果测试失败自动触发“修复测试失败”技能。如果技能修复成功自动提交修复如果修复失败通知开发者介入。这种融合的关键是明确技能的边界和人的边界。技能负责处理明确、重复、可验证的任务人负责处理模糊、复杂、需要判断的任务。两者配合才能发挥最大效果。另外技能体系需要和代码评审流程结合。技能修改的代码同样需要评审不能因为“是AI改的”就跳过评审。评审时重点关注修改是否符合预期、是否引入了新问题、是否遵循了代码规范。6.4 后续可以扩展的方向技能体系搭建起来之后有几个方向可以继续扩展。一是增加更多类型的技能比如代码审查、性能优化、安全扫描。二是提升技能的智能化程度比如让技能能够根据历史执行记录自动调整参数。三是把技能体系开放给团队让每个人都能贡献技能形成共享的技能库。我自己的计划是先把手头的几个核心技能做扎实确保稳定可靠然后再逐步扩展。技能体系的价值在于用起来而不是在于写得多。一个稳定可靠的技能比十个半成品技能更有价值。最后分享一个小技巧写技能定义时先用手动方式执行一遍任务把每一步的操作和判断都记录下来然后再把这些记录整理成技能定义。这样写出来的技能最贴近实际也最容易验证。我试过直接凭想象写技能定义结果执行时发现很多步骤在实际中根本行不通。手动执行一遍再写效率高很多。