1. 为什么“让AI记住工作方式”比换一个更强的模型更值钱大多数人用AI的方式本质上是在做“一次性交易”打开对话框敲一段提示词拿到结果关掉。下一次再打开AI对你一无所知你得从头解释一遍“我是做后端开发的”“我们团队用特定的提交规范”“文档要按这个模板写”。这种重复劳动消耗的不仅是时间更是耐心。Agent-Skills 这个方向要解决的就是这件事。它的核心思路很朴素把“你希望AI怎么干活”这件事从每次对话里临时交代变成一份持久化的、结构化的技能描述文件让AI在需要的时候自动加载并遵循。关键词里出现的 SKILL.md、skill-creator、Eval分别对应了这套机制的三个关键环节——技能怎么定义、技能怎么生成、技能怎么验证。我最初接触这个概念时第一反应是“这不就是系统提示词吗”。但实际用下来发现差别很大。系统提示词是一坨静态文本塞进上下文就完事而 Agent-Skills 更像是一套可插拔的能力模块每个技能有明确的触发条件、执行步骤和验收标准。打个比方系统提示词像是给新员工发一本员工手册而 Agent-Skills 像是给老员工配了一套标准作业程序SOP每道工序都有对应的操作卡用哪张抽哪张。这套东西适合谁如果你每天要用AI处理重复性任务——写周报、做代码审查、整理会议纪要、生成测试用例——那它值得你花时间搭一套。如果你只是偶尔问问天气、查查资料那确实没必要。判断标准很简单同一个类型的任务你向AI解释过三次以上就该把它固化成一个技能。2. SKILL.md 到底该写什么从“提示词堆砌”到“结构化技能定义”2.1 一个技能文件的四个必备区块很多人第一次写 SKILL.md会把它写成一段很长的提示词恨不得把所有可能遇到的情况都塞进去。结果就是文件臃肿、触发不准、维护困难。我踩过这个坑之后总结出一个技能文件应该包含四个区块每个区块各司其职。第一个区块是元信息。这部分回答“这个技能叫什么、什么时候用”。名称要短且唯一触发条件要写清楚什么场景下应该激活这个技能。比如“代码审查”这个技能触发条件可以写成“当用户提交代码片段并请求审查时”或者“当对话中出现‘review’‘检查代码’等意图时”。触发条件写得太宽技能会被频繁误触发写得太窄该用的时候用不上。第二个区块是前置约束。这部分回答“执行这个技能之前需要满足什么条件”。比如代码审查技能可能需要知道项目的编程语言、代码规范版本、是否有特定的安全检查清单。这些信息如果缺失技能执行出来的结果就会跑偏。我的做法是在这里列出必需的输入项并给出默认值或获取方式。第三个区块是执行步骤。这是技能的核心回答“具体怎么做”。关键是要把步骤写成有序的、可验证的动作序列而不是模糊的描述。比如不要写“检查代码质量”而要写“逐函数检查是否存在未处理的异常分支检查所有外部调用的超时设置检查日志输出是否包含敏感信息”。步骤越具体AI执行时的偏差越小。第四个区块是输出规范。这部分回答“结果长什么样”。包括输出格式Markdown表格、JSON、纯文本、必须包含的字段、严重程度的分级标准等。我见过很多技能定义失败就是因为输出规范没写清楚AI每次返回的格式都不一样后续根本没法自动化处理。2.2 触发条件的设计精准比宽泛更重要触发条件是 SKILL.md 里最容易被低估的部分。我一开始写触发条件时总想着“覆盖面广一点这样什么情况都能用上”。结果就是技能被频繁激活但很多场景下根本不需要它反而干扰了正常对话。后来我改用“意图上下文”的双重判断逻辑。意图层面明确列出哪些用户表达会触发这个技能上下文层面要求同时满足某些条件才激活。举个例子一个“生成单元测试”的技能意图层面匹配“写测试”“生成测试用例”等表达上下文层面要求“当前对话中已经存在被测试的代码片段”。两个条件同时满足才触发准确率大幅提升。还有一个实用技巧在触发条件里加入排除项。比如“代码审查”技能可以排除“用户只是粘贴代码但没有请求审查”的情况。排除项写得好能过滤掉大量误触发。2.3 执行步骤的粒度控制太粗会跑偏太细会僵化执行步骤写多细是个需要反复调试的问题。写得太粗比如“分析代码并给出改进建议”AI会自由发挥每次结果差异很大。写得太细比如“第一步打开编辑器第二步定位到第10行”又会把AI当成脚本执行器丧失了它应有的灵活性。我的经验是步骤描述“做什么”和“为什么做”但不规定“具体怎么实现”。比如代码审查技能里我会写“检查所有数据库查询是否存在N1问题因为这类问题在数据量增长后会显著拖慢响应速度”而不是写“搜索所有for循环里包含查询调用的代码”。前者给了AI判断的依据后者把AI限制死了。另外步骤之间要有明确的依赖关系。哪些步骤可以并行哪些必须串行哪些步骤的结果是后续步骤的输入这些都要在 SKILL.md 里体现出来。我通常用有序列表加依赖标注的方式来表达比如“步骤3依赖步骤1的输出”。3. skill-creator 的实战用法让AI自己生成技能初稿3.1 为什么需要 skill-creator手写 SKILL.md 最大的问题是效率低。一个中等复杂度的技能从构思到写完再到调试通过可能要花一两个小时。而且写出来的第一版往往有很多遗漏需要反复迭代。skill-creator 的思路是让AI根据你的描述先生成一个技能初稿你在这个基础上修改效率能提升好几倍。我实测下来的流程是这样的先用自然语言向 skill-creator 描述你想要的能力比如“我需要一个技能当我给出一个Python函数时它能帮我生成对应的pytest测试用例要求覆盖正常路径、边界条件和异常分支”。skill-creator 会返回一个结构化的 SKILL.md 初稿包含元信息、触发条件、执行步骤和输出规范。3.2 给 skill-creator 的输入该怎么写skill-creator 的输出质量很大程度上取决于你给它的输入。我总结了一个输入模板包含五个要素能力描述、使用场景、输入形式、输出要求、约束条件。能力描述用一句话说清楚这个技能做什么。使用场景列举两到三个典型场景帮助 skill-creator 理解触发条件该怎么写。输入形式说明用户会以什么方式提供数据是粘贴代码、上传文件还是对话描述。输出要求明确格式和必须包含的内容。约束条件列出不能做什么比如“不要生成依赖外部服务的测试用例”。这五个要素给全了skill-creator 生成的初稿基本能到七十分。剩下的三十分靠人工调整主要是触发条件的精准度和执行步骤的粒度。3.3 初稿生成后的三处必改skill-creator 生成的初稿有三处我每次都会改。第一处是触发条件初稿通常写得比较宽泛需要根据实际使用场景收窄。第二处是执行步骤的依赖关系初稿往往把所有步骤平铺没有标注哪些步骤可以并行、哪些必须串行。第三处是输出规范的边界情况初稿一般只覆盖正常情况异常情况下的输出格式需要手动补充。改完这三处之后我会把技能文件放进实际对话里跑几轮观察触发是否准确、执行是否稳定、输出是否符合预期。通常再迭代两到三轮一个可用的技能就成型了。4. Eval 环节怎么判断一个技能是真的能用还是看起来能用4.1 技能评估的三个维度Eval 这个词在 AI 工程实践里经常出现但在 Agent-Skills 的语境下它特指对技能文件的质量评估。我把它拆成三个维度触发准确性、执行稳定性、输出一致性。触发准确性衡量的是“该触发的时候触发了吗不该触发的时候触发了吗”。测试方法是准备一组正例和反例正例是应该触发技能的用户输入反例是不应该触发的输入然后统计准确率和召回率。我一般要求正例召回率在90%以上反例误触发率在10%以下。执行稳定性衡量的是“同样的输入多次执行的结果是否一致”。测试方法是同一个输入跑五到十次对比每次的执行步骤和输出结果。如果差异很大说明执行步骤的描述不够明确需要补充约束。输出一致性衡量的是“输出格式是否符合规范”。测试方法是检查每次输出的结构是否完整、字段是否齐全、格式是否统一。这个维度最容易达标只要输出规范写清楚了基本不会出问题。4.2 构造测试用例的实用方法构造测试用例是 Eval 环节最耗时的工作。我的做法是从实际使用记录里提取。平时用AI处理任务时把那些“本来应该用技能来处理”的输入记录下来攒够二十条左右就形成了一组测试用例。这些用例要覆盖几种典型情况标准输入完全符合技能预期、边界输入缺少某些信息或格式略有偏差、干扰输入看起来像但实际不应该触发技能。每种情况至少准备五条这样评估结果才有统计意义。还有一个技巧是用AI生成测试用例。把技能文件给到AI让它根据技能定义生成一组测试输入然后人工筛选和补充。这个方法能快速得到一批候选用例虽然质量参差不齐但筛选成本比从零构造低得多。4.3 评估结果不达标时的排查顺序当评估结果不达标时我按照固定的顺序排查。先看触发条件大部分问题出在这里。触发条件太宽就收窄太窄就放宽排除项不够就补充。然后看执行步骤如果触发准确但执行结果不稳定说明步骤描述需要细化。最后看输出规范如果执行稳定但格式不对说明输出规范有遗漏。这个排查顺序的逻辑是触发条件是入口入口不对后面全错执行步骤是过程过程不稳结果就不可靠输出规范是出口出口不统一就没法自动化。按这个顺序排查通常两三轮就能把技能调到可用状态。5. 多技能协作时的冲突处理与优先级设计5.1 技能冲突的两种典型场景当你有多个技能时冲突几乎不可避免。我遇到最多的是两种场景触发条件重叠和执行步骤矛盾。触发条件重叠是指两个技能的触发条件有交集导致同一个输入可能激活两个技能。比如“代码审查”和“代码重构”两个技能都可能被“帮我看看这段代码”触发。执行步骤矛盾是指两个技能对同一件事有不同的处理方式比如一个技能要求输出JSON格式另一个要求输出Markdown表格。5.2 用优先级和互斥规则解决冲突解决触发条件重叠我用的方法是给每个技能设置优先级并在技能文件里声明互斥关系。优先级高的技能先触发触发后检查是否满足互斥条件如果满足就抑制低优先级技能。具体实现上我在技能文件的元信息里加两个字段priority和excludes。priority是一个数字数字越小优先级越高。excludes是一个列表列出与当前技能互斥的技能名称。当多个技能同时满足触发条件时按优先级排序依次检查互斥关系最终只激活一个技能。解决执行步骤矛盾我用的方法是统一输出规范。所有技能的输出都遵循同一套基础格式技能特有的输出内容放在扩展字段里。这样即使多个技能先后执行输出结果也能拼接在一起而不冲突。5.3 技能编排的串行与并行策略有些任务需要多个技能协作完成这时候就要设计编排策略。串行策略适用于有明确先后依赖的任务比如先“代码审查”再“生成测试”再“生成文档”。并行策略适用于相互独立的任务比如同时“检查代码规范”和“检查安全漏洞”。我在编排时遵循一个原则能并行就并行必须串行才串行。并行能节省时间但会增加结果合并的复杂度。串行简单可靠但耗时更长。实际使用中我会先尝试并行如果结果合并出现问题再改成串行。编排策略写在技能文件的元信息里用一个orchestration字段描述。这个字段包含两个子字段mode表示串行还是并行dependencies表示依赖关系。这样AI在执行时就能按照编排策略自动调度。6. 把技能文件纳入版本管理迭代、回滚与团队共享6.1 技能文件的版本管理策略技能文件是需要持续迭代的。每次发现触发不准、执行不稳、输出不对都要修改技能文件。如果没有版本管理改着改着就乱了想回滚都找不到之前的版本。我的做法是把技能文件放在Git仓库里管理每个技能一个目录目录下放 SKILL.md 和相关的测试用例。每次修改都提交一次提交信息写清楚改了什么、为什么改。这样不仅能回滚还能看到技能的演进过程。版本号我用语义化版本规范主版本号在技能定义发生不兼容变更时递增次版本号在新增能力时递增修订号在修复问题时递增。这样一看版本号就知道这次改动的影响范围。6.2 团队共享时的命名规范与目录结构团队共享技能文件时命名规范和目录结构很重要。我用的规范是技能名称用短横线分隔的小写英文比如code-review、test-generator。目录结构按功能分类比如skills/coding/、skills/writing/、skills/analysis/。每个技能目录下至少包含三个文件SKILL.md是技能定义test-cases.md是测试用例CHANGELOG.md是变更记录。如果技能有依赖的外部资源比如模板文件、配置示例也放在同一个目录下。共享方式我推荐用Git子模块或者包管理工具。Git子模块适合技能数量不多、更新频率不高的场景。包管理工具适合技能数量多、需要版本锁定的场景。不管用哪种方式都要确保团队成员能方便地获取最新版本同时能锁定自己依赖的版本。6.3 技能迭代的触发信号技能什么时候该迭代我总结了几个触发信号。触发准确率下降是最明显的信号说明使用场景发生了变化触发条件需要调整。输出格式频繁被手动修正说明输出规范有遗漏。执行步骤被反复跳过或修改说明步骤描述与实际需求脱节。**用户反馈“这个技能不好用”**是最直接的信号虽然模糊但值得深挖。每次迭代后我都会跑一遍Eval流程确认三个维度的指标没有退化。如果某个指标退化了就回滚到上一个版本重新分析问题。这个习惯帮我避免了很多“改了一个问题引入两个新问题”的情况。7. 我踩过的五个坑和对应的解法7.1 坑一技能文件写成了提示词大全第一个坑是刚开始写 SKILL.md 时把它当成提示词来写把所有能想到的情况都塞进去。结果文件超过两千字触发条件模糊执行步骤冗长AI执行时经常跑偏。解法是做减法。一个技能只解决一类问题触发条件只覆盖核心场景执行步骤只写关键动作。我把这个原则总结成一句话技能文件不是百科全书是操作手册。操作手册的特点是步骤清晰、重点突出、不废话。7.2 坑二触发条件写得太宽导致误触发第二个坑是触发条件写得太宽。我写了一个“文档生成”技能触发条件里写了“当用户提到文档时”。结果用户说“帮我看看这个文档”也会触发但实际上用户只是想让我阅读文档不是生成文档。解法是加限定词。触发条件里不仅要有意图词还要有动作词和对象词。比如“生成文档”这个意图要同时匹配“生成”“创建”“写”等动作词以及“文档”“报告”“说明”等对象词。两个条件同时满足才触发准确率大幅提升。7.3 坑三执行步骤缺少异常处理分支第三个坑是执行步骤只写了正常流程没写异常处理。比如“读取文件内容”这一步如果文件不存在怎么办如果文件格式不对怎么办如果文件太大读不完怎么办这些情况没写AI遇到时就会自由发挥结果不可控。解法是给每个关键步骤加异常分支。格式是“步骤X执行某操作。如果遇到情况A则执行A1如果遇到情况B则执行B1”。异常分支不用写太多覆盖最常见的两三种就行。写多了反而会让技能文件臃肿。7.4 坑四输出规范没有定义空值和错误情况第四个坑是输出规范只定义了正常情况下的格式没定义空值和错误情况。比如一个“数据提取”技能正常情况输出JSON但如果没提取到数据输出什么如果提取过程出错输出什么这些没定义AI就会随机发挥。解法是在输出规范里明确三种状态成功、空结果、错误。每种状态定义对应的输出格式和字段。成功状态输出完整数据空结果状态输出空数组或空对象并附带说明错误状态输出错误码和错误信息。这样无论哪种情况输出都是可预期的。7.5 坑五技能之间没有隔离导致相互干扰第五个坑是多个技能之间没有隔离。我同时激活了“代码审查”和“代码格式化”两个技能结果代码审查技能的输出被格式化技能修改了导致审查结果丢失。解法是给每个技能定义独立的输出空间。技能执行时输出先写入自己的空间最后由编排层统一合并。合并时按照技能优先级和依赖关系决定顺序避免相互覆盖。这个机制在技能文件里通过output-space字段声明编排层根据这个字段做隔离。8. 从单技能到技能库规模化之后的组织方式8.1 技能分类的维度选择当技能数量超过十个就需要分类组织了。我试过几种分类维度最后固定用“领域功能”两级分类。领域包括编码、写作、分析、运维等功能包括生成、审查、转换、提取等。一个技能同时属于一个领域和一个功能比如“代码审查”属于“编码审查”。这个分类方式的好处是查找方便。想找“生成类”的技能就看所有功能为“生成”的技能想找“编码类”的技能就看所有领域为“编码”的技能。两个维度交叉定位很快。8.2 技能索引的维护技能多了之后需要一个索引来快速查找。我用一个 Markdown 表格维护技能索引包含技能名称、所属领域、所属功能、触发条件摘要、优先级、依赖关系。这个索引放在技能库的根目录下每次新增或修改技能时同步更新。索引的另一个用途是冲突检测。新增技能时对照索引检查触发条件是否与现有技能重叠、执行步骤是否矛盾、输出规范是否冲突。提前发现冲突比事后调试成本低得多。8.3 技能库的定期清理技能库需要定期清理。我每个季度做一次清理检查每个技能的使用频率和评估指标。使用频率低且评估指标一般的技能考虑合并或删除。使用频率高但评估指标下降的技能安排迭代优化。清理的标准我定得很简单三个月内没有被触发过的技能要么删除要么合并到其他技能里。这个标准帮我保持技能库的精简避免维护成本无限增长。9. 关于 Agent-Skills 的几个常见误解9.1 误解一技能越多越好很多人觉得技能越多AI的能力越强。实际上技能多了之后触发冲突、维护成本、认知负担都会增加。我的经验是十个精心维护的技能比一百个粗制滥造的技能有用得多。技能的价值在于质量不在于数量。9.2 误解二技能写一次就不用管了技能不是写完就一劳永逸的。使用场景在变AI模型在变团队需求在变技能也需要跟着变。我把技能维护当成一项持续工作每次使用中发现的问题都记录下来定期集中迭代。不维护的技能很快就会变得不可用。9.3 误解三技能可以完全替代人工判断技能能固化的是流程和标准不能替代的是判断和决策。比如代码审查技能能检查出常见的代码问题但架构是否合理、设计是否优雅这些需要人工判断。我把技能定位成“第一道过滤器”它处理掉80%的常规问题剩下20%的复杂问题留给人来处理。9.4 误解四技能文件越详细越好技能文件的详细程度要适中。太简略AI执行时自由发挥空间太大结果不稳定。太详细AI被限制得太死遇到技能文件没覆盖的情况就不知道怎么处理。我的经验是关键步骤写清楚边缘情况给原则具体实现留空间。这样既保证了稳定性又保留了灵活性。10. 一个完整技能从构思到上线的实操记录10.1 需求分析与技能边界划定我以“生成API文档”这个技能为例记录完整的实操过程。需求来自团队反馈每次写完接口都要手动整理文档费时且容易遗漏。我决定做一个技能输入接口代码输出标准格式的API文档。划定技能边界时我明确了三件事这个技能只处理RESTful接口不处理GraphQL和gRPC只生成文档内容不负责发布到文档平台只覆盖常见的HTTP方法和参数类型特殊协议需要人工补充。边界划清楚了技能文件就不会无限膨胀。10.2 用 skill-creator 生成初稿并人工调整我把需求描述给到 skill-creator输入包含能力描述、使用场景、输入形式、输出要求和约束条件。skill-creator 返回了一个初稿包含元信息、触发条件、执行步骤和输出规范。人工调整主要集中在三处触发条件从“当用户提到API文档时”收窄为“当用户提供接口代码并请求生成文档时”执行步骤补充了参数类型映射规则和异常处理分支输出规范增加了空值和错误情况的定义。调整后的技能文件大约八百字比初稿精简了不少。10.3 Eval 测试与迭代过程Eval 测试我准备了十五个用例五个标准输入、五个边界输入、五个干扰输入。标准输入是完全符合预期的接口代码边界输入是缺少部分信息的代码干扰输入是看起来像接口代码但实际不是的片段。第一轮测试结果标准输入全部通过边界输入有三个失败干扰输入有两个误触发。分析原因边界输入失败是因为执行步骤没有处理“参数类型缺失”的情况干扰输入误触发是因为触发条件没有排除“代码片段不完整”的情况。针对这两个问题修改技能文件第二轮测试全部通过。10.4 上线后的监控与反馈收集技能上线后我做了两件事一是记录每次触发的情况包括输入摘要、执行结果、用户反馈二是每周汇总一次看触发频率和成功率的变化。上线第一周触发十二次成功十次两次失败都是因为接口代码格式特殊。我把这两个案例补充到测试用例里同时修改执行步骤增加对特殊格式的处理。第二周触发十五次全部成功。第三周开始触发频率稳定在每周十到十五次成功率保持在95%以上。这个技能从构思到上线总共花了大约四个小时。其中需求分析和边界划定占了一小时skill-creator 生成初稿和人工调整占了一小时Eval 测试和迭代占了一小时上线监控和反馈收集占了一小时。相比每次手动整理文档的时间这个投入在两周内就回本了。11. 技能文件的长期维护什么时候该重构什么时候该放弃11.1 重构的信号与时机技能文件需要重构的信号有几个文件超过一千五百字、执行步骤超过十五步、触发条件超过五条、输出规范超过三个版本。出现这些信号时说明技能已经变得臃肿需要拆分或简化。重构的时机我选在季度清理时。平时发现问题先记录不急着改攒到季度清理时集中处理。这样避免频繁修改导致的版本混乱也避免打断正常使用。重构的方式有两种拆分和简化。拆分是把一个臃肿的技能拆成多个小技能每个小技能负责一个子场景。简化是删掉不常用的触发条件、合并相似的执行步骤、统一输出规范。选择哪种方式看技能的实际使用情况。如果技能覆盖的场景差异大就拆分如果场景单一但实现复杂就简化。11.2 放弃一个技能的判断标准不是所有技能都值得维护。放弃一个技能的判断标准有三个使用频率持续下降、维护成本超过收益、被其他技能替代。使用频率持续下降说明这个技能对应的需求在减少。维护成本超过收益说明这个技能太复杂每次修改都要花大量时间但带来的效率提升有限。被其他技能替代说明有更好的方式实现同样的能力。出现这三个信号中的任何一个我都会考虑放弃这个技能。放弃的方式不是直接删除而是先标记为“废弃”保留三个月。三个月内如果没有人使用就正式删除。这样避免误删还有用的技能。11.3 技能库的健康度指标我用量化指标来监控技能库的健康度。平均触发准确率反映技能的整体质量低于85%就需要排查。平均执行稳定性反映技能的可靠性低于90%就需要优化。技能平均年龄反映技能的更新频率超过六个月就需要检查是否过时。技能使用分布反映技能库的均衡性如果80%的触发集中在20%的技能上说明其他技能可能需要清理。这些指标我每个月统计一次记录在技能库的 README 里。趋势比绝对值更重要如果指标持续下降就说明技能库需要一次大的整理。12. 关于 Agent-Skills 的一些个人体会我用了大半年 Agent-Skills最大的体会是它改变的不是AI的能力而是我和AI协作的方式。以前我把AI当成一个需要反复交代的临时工现在我把AI当成一个熟悉我工作习惯的搭档。这个转变带来的效率提升比换一个更强的模型明显得多。另一个体会是技能文件的质量取决于你对自身工作流程的理解深度。如果你自己都说不清楚一件事该怎么做那写出来的技能文件一定是模糊的。写技能文件的过程其实也是梳理自己工作方法的过程。我通过写技能文件发现了很多自己工作中“凭感觉做”但实际有规律可循的环节。最后一个体会是不要追求一步到位。我最早的几个技能文件写得很粗糙但正是这些粗糙的技能文件让我知道了哪里需要改进。先写一个能用的版本然后在使用中迭代比一开始就追求完美要实际得多。技能文件是长出来的不是设计出来的。