1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会一头雾水。它既不是某个具体软件的名字也不是一个明确的技术名词而是一个在AI编程工具生态里被反复提及、却很少有人系统讲清楚的概念。结合热搜词里高频出现的 Claude、Agent Skills、SKILL.md、Claude Code 这些词可以基本确定这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 这类命令行/桌面端工具构建的一套技能扩展机制——用结构化的文件描述一个可复用的能力单元让 AI 在特定场景下按预设的方式工作。打个比方AI 编程助手本身像一个刚入职的聪明新人通用能力强但不懂你们公司的具体规矩。skills 就是你写给它的岗位操作手册遇到什么任务、按什么流程走、调用哪些工具、输出什么格式全都写清楚。它不需要你每次重新解释只要触发对应场景就自动按手册执行。这套机制解决的核心痛点是重复性指令的沉淀问题。没有 skills 的时候你每次让 AI 做代码审查、写单元测试、生成接口文档都得把要求重新描述一遍措辞稍有不同结果就飘。有了 skills这些要求变成文件一次写好、反复调用输出稳定性大幅提升。适合读这篇内容的人大致分三类一是刚接触 Claude Code、还在摸索怎么让它听话的新手二是已经用了一段时间、但每次都要重复交代背景的中级用户三是想把自己团队的开发规范固化成 AI 可执行资产的工程师或技术负责人。不管你在哪一层下面这些内容都能对上号。需要先说明一点skills 的具体实现细节在不同工具、不同版本间有差异本文讲的是通用思路和常见实践具体到你的环境以官方文档为准。但底层逻辑是相通的理解了就不容易迷路。2. SKILL.md 的骨架一个技能文件里到底装了什么2.1 为什么是 Markdown 而不是配置文件很多人第一反应会问既然是给程序读的为什么不用 JSON 或 YAML 这种结构化格式反而用 Markdown这个问题问到点子上了。原因在于 skills 的消费方是大语言模型不是传统解析器。模型对自然语言的理解能力远强于对严格语法的解析能力。用 Markdown 写你可以用标题分层、用列表列步骤、用代码块给示例模型读起来上下文清晰人读起来也舒服。如果硬用 JSON光是转义和嵌套就能把人逼疯而且模型对深层嵌套结构的理解反而不如平铺的自然语言。Markdown 还有一个隐性优势它天然适合版本管理。diff 出来一目了然谁改了哪句话、加了哪个步骤代码审查时看得清清楚楚。这对团队协作场景特别重要。2.2 一个技能文件的典型组成虽然不同工具的字段命名有出入但一个完整的技能描述文件通常包含这几块内容我用表格对照说明组成块作用常见写法名称与描述告诉系统这个技能叫什么、什么时候该用它顶部元信息或一级标题触发条件明确什么场景下激活这个技能当用户要求……时执行步骤具体怎么做分步骤列出有序列表输入输出约定需要什么信息、产出什么格式参数说明 示例边界与禁忌什么不能做、什么情况要停下来问注意事项段落参考示例一两个正例帮模型对齐预期代码块或对话示例这里最关键的是触发条件和边界与禁忌两块恰恰是新手最容易忽略的。很多人写技能只写怎么做不写什么时候做和什么时候别做结果模型在不该用的时候乱用或者该用的时候没反应。2.3 描述文字的颗粒度怎么把握写技能描述时颗粒度是个反复要权衡的问题。写太粗模型自由发挥空间大输出不稳定写太细又变成死板的脚本失去 AI 的灵活性。我的经验是流程性内容写细判断性内容写粗。比如先读取文件、再提取函数签名、最后生成文档这种步骤写细一点没关系反正顺序是固定的。但根据代码复杂度决定是否拆分这种判断就别写死阈值给个方向让模型自己权衡。举个具体的反例。有人写技能时规定如果函数超过 50 行就拆分结果遇到一个 51 行但逻辑紧密的函数模型硬拆反而破坏了可读性。更好的写法是关注函数职责是否单一行数只是参考信号之一。把判断权交还给模型同时给出判断维度这才是技能描述该有的样子。3. 触发机制技能是怎么被叫醒的3.1 显式调用与隐式匹配的区别技能被激活的方式大致分两种。一种是显式调用你直接说用 XX 技能处理这个模型明确知道要调用哪个。另一种是隐式匹配你只是描述任务系统根据技能描述里的触发条件自动判断该用哪个。显式调用稳定但需要你记住技能名字用起来有负担。隐式匹配省事但对技能描述的触发条件要求很高——写得不清楚模型就匹配不上或者匹配到错误的技能。实际使用中我建议关键流程用显式辅助能力用隐式。比如代码发布这种一步错步步错的流程显式调用确保万无一失。而像帮我看看这段代码有没有明显问题这种日常小任务交给隐式匹配就够了没必要每次都点名。3.2 触发条件写不好的三种典型症状症状一技能从不触发。你写了个技能但用的时候模型完全不理。八成是触发条件写得太窄或者用了模型不敏感的词。解决办法是把触发条件往宽了写多列几个同义场景。症状二技能乱触发。你只想让它处理 A 场景结果 B、C、D 场景它都往上套。这通常是触发条件写得太泛或者技能描述里出现了太多通用词。收窄描述把不相关的场景明确排除掉。症状三多个技能抢触发。你写了两个技能触发条件有重叠模型不知道该用哪个。这时候要么合并技能要么在描述里写清楚优先级和适用边界。提示调试触发问题时可以故意构造几个边界场景去测试看模型的实际反应比盯着描述文字空想有效得多。3.3 一个触发条件的具体写法对比光说理论太虚直接看对比。下面是一个生成接口文档技能的触发条件两种写法写法 A太窄当用户说生成接口文档时触发。写法 B合理当用户要求为某个 API、接口、endpoint 生成文档 或要求整理请求参数、响应结构、错误码说明时触发。 不适用于生成数据库表结构文档、生成前端组件文档。写法 B 覆盖了同义表达同时用不适用于划清了边界。实测下来B 的触发准确率明显高于 A。这个技巧在写任何技能时都适用正向列举 反向排除双管齐下。4. 从零写一个技能完整流程拆解4.1 先想清楚这个技能解决什么重复劳动动手写之前先问自己一个问题这个技能要替代的是哪段重复劳动如果答不上来说明还没到写技能的时候。好的技能候选通常满足三个特征高频经常要做、稳定每次做法基本一致、有明确产出做完有个可检验的结果。比如把一段 SQL 转成对应的 ORM 查询代码就符合而帮我思考一下架构就不适合做成技能因为太开放没有稳定产出。我见过有人一上来就想写个万能编程助手技能结果写了几百行模型根本用不明白。技能要小而专一个技能干好一件事比一个大而全的技能有用得多。4.2 起草技能文件的实操顺序确定要写什么之后按这个顺序起草先写触发条件。明确什么时候用、什么时候不用这是地基。再写执行步骤。把你自己做这件事的流程拆成步骤一步一句别合并。补输入输出约定。需要用户提供什么、最终产出什么格式写清楚。加边界与禁忌。哪些情况要停下来问、哪些操作绝对不能做。最后放示例。一个正例足够多了反而干扰。这个顺序的好处是每一步都建立在前一步的基础上不会写着写着跑偏。很多人习惯先写步骤最后才想触发条件结果发现步骤和触发场景对不上返工。4.3 步骤描述里的意图比动作更重要写执行步骤时新手容易写成纯动作流水账读取文件、解析、输出。这种写法模型能执行但遇到变体就懵。更好的做法是动作 意图。比如不写读取文件而写读取目标文件目的是获取完整的函数定义注意不要遗漏被注释掉的代码块。多了半句意图说明模型在遇到边界情况时就知道该怎么权衡。这个技巧来自一个教训。我曾经写了个代码重构技能步骤里只写提取重复代码结果模型把两段看起来像、实际语义不同的代码也合并了引入 bug。后来改成提取语义等价的重复代码判断等价性时优先看逻辑而非字面相似度问题就没了。意图描述是给模型的判断依据不是废话。4.4 写完之后的验证方法技能写完不能直接用得验证。我的验证分三步第一步正例测试。构造一个典型场景看技能是否触发、执行是否符合预期。第二步反例测试。构造一个不该触发的场景看技能是否安分。第三步边界测试。构造一个模棱两可的场景看模型怎么处理据此调整描述。这三步走下来基本能发现大部分问题。别嫌麻烦技能是要反复用的前期多花十分钟调试后期省下的是几十次重复解释。5. 技能库的组织与复用别让技能变成新的混乱5.1 技能多了之后怎么分类写了两三个技能时随便放哪都行。写到十几个就得考虑分类了。常见的分类维度有按功能域代码类、文档类、数据类、按使用频率高频、低频、按团队归属通用、某项目专用。我倾向于按功能域分因为找技能时人脑是按我要干什么检索的不是按这个技能多常用检索的。目录结构大致长这样skills/ code/ review.md refactor.md docs/ api-doc.md changelog.md data/ sql-convert.md简单直接一眼能找到。别搞太深的嵌套三层以上就开始烦了。5.2 技能之间的依赖与冲突技能不是孤立的。有的技能会调用另一个技能的能力有的技能之间触发条件重叠。这时候要处理好依赖和冲突。依赖关系建议显式声明。在技能描述里写一句本技能依赖 XX 技能的输出格式模型就知道要先确保那个技能可用。冲突关系则通过边界排除解决在各自的不适用于里写清楚。有个容易踩的坑两个技能都定义了同名的输出格式但格式细节不一致模型混用后产出四不像。解决办法是把公共格式抽出来单独定义两个技能都引用它而不是各写各的。5.3 版本管理与团队共享技能文件既然是文本就该纳入版本管理。每次修改都提交写清楚改了什么、为什么改。这样出问题时能回溯团队协作时也能看到演进过程。团队共享时建议维护一个技能索引文件列出所有可用技能、各自用途、维护人。新人进来先看索引比一个个翻文件高效得多。索引不用花哨一个表格就够技能名用途维护人最近更新code-review代码审查张三2024-XXapi-doc接口文档生成李四2024-XX这个表格看着简单但能省下大量这个技能谁写的、还能不能用的沟通成本。6. 实战中踩过的坑与排查思路6.1 技能不生效的完整排查链路技能写了但没反应这是最高频的问题。别急着重写按这个链路排查第一确认文件位置对不对。不同工具对技能文件的存放路径有要求放错地方系统根本扫不到。先查文档确认路径。第二确认文件格式对不对。Markdown 语法错误、编码问题都可能导致解析失败。用纯文本编辑器打开看看有没有乱码。第三确认触发条件是否匹配。把你实际说的话和技能里写的触发条件逐字对比看差在哪。经常是用户说的词和技能里写的词对不上。第四确认是否有更高优先级的技能拦截。如果同时有多个技能可能触发检查是不是被别的技能抢了。第五看日志。多数工具会输出技能匹配的日志直接看系统认为该用哪个技能比猜快得多。这个链路我走过很多次八成的问题在前三步就能定位。剩下两成看日志基本能解决。6.2 输出不稳定的三种归因技能触发了但每次输出质量参差不齐这也是常见困扰。归因下来无非三种描述模糊。技能里用了适当合理尽量这类词模型每次理解都不一样。解决办法是把模糊词替换成可判断的标准或者明确说明由模型根据上下文判断。示例不足或示例误导。只给一个示例模型可能过度拟合示例本身有瑕疵模型会学坏。建议给一到两个高质量示例确保示例本身经得起推敲。上下文干扰。当前对话里其他内容影响了模型判断。这种情况可以在技能里加一句忽略与本次任务无关的历史上下文帮模型聚焦。6.3 一个真实的排查案例有次我写了个生成单元测试的技能触发正常但生成的测试有时覆盖率高、有时只测了主流程。排查后发现问题出在步骤描述里写了为关键函数生成测试但关键没定义。模型有时理解为所有公开函数有时理解为核心业务函数。修改方案是把关键替换成明确标准为所有导出函数生成测试内部辅助函数若包含复杂逻辑也需覆盖。改完之后输出就稳定了。这个案例说明技能描述里的每个形容词都可能是隐患能量化就量化不能量化就明确判断维度。7. 进阶玩法让技能组合出更大价值7.1 技能链把多个技能串成工作流单个技能解决单点问题把多个技能串起来就能解决流程问题。比如代码审查 → 生成修复建议 → 自动应用修复 → 生成变更说明这条链每个环节一个技能串起来就是完整的代码维护流程。串链的关键是接口对齐。上一个技能的输出格式要正好是下一个技能的输入格式。这需要在设计技能时就考虑好上下游或者后期做格式适配。7.2 参数化技能一个技能应对多种场景有些技能场景相似但细节不同没必要写多个做成参数化即可。比如生成文档技能通过参数区分是生成 API 文档还是模块文档共用大部分逻辑只在输出格式上分叉。参数化的好处是维护成本低改一处全生效。坏处是描述会变复杂触发判断难度上升。权衡下来场景差异小于三成时参数化大于三成时拆开写这是我摸索出的经验线。7.3 技能的自省与迭代技能不是写完就完事要定期回顾。我习惯每个月翻一遍自己的技能库看哪些很久没用可能该删、哪些经常出问题该改、哪些场景变了该更新。迭代时保留修改记录写清楚每次改动的动机。过几个月回头看这些记录能帮你回忆起当时的思考避免重复踩坑。技能库就像代码库需要持续维护放着不管就会腐烂。8. 关于学习路径的一点个人体会回到热搜词里那个问题——如何学习 skills。我的看法是这东西没法纯靠看文档学会必须动手写。看十篇教程不如自己写一个技能、踩一次坑、改一版。入门路径我建议这样走先照着别人的技能改一个理解结构然后从自己最高频的重复劳动入手写第一个原创技能跑通之后再尝试写第二个、第三个慢慢形成自己的技能库。过程中遇到问题优先看日志、做对比测试而不是到处问人。还有个心态问题。很多人写技能追求一步到位写一个完美的。实际上技能是迭代出来的第一版能用就行后面根据实际使用慢慢打磨。我最早的几个技能现在回头看写得很粗糙但正是它们让我理解了这套机制才有了后面更成熟的版本。技能这东西本质是把你脑子里的隐性经验显性化。写的过程本身就是一次对自己工作方式的梳理。写得越多你会越清楚自己到底在重复做什么、哪些环节可以固化、哪些必须保留灵活性。这个认知比技能本身更有价值。
AI编程助手技能扩展机制：SKILL.md编写与Claude Code实战指南
1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会一头雾水。它既不是某个具体软件的名字也不是一个明确的技术名词而是一个在AI编程工具生态里被反复提及、却很少有人系统讲清楚的概念。结合热搜词里高频出现的 Claude、Agent Skills、SKILL.md、Claude Code 这些词可以基本确定这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 这类命令行/桌面端工具构建的一套技能扩展机制——用结构化的文件描述一个可复用的能力单元让 AI 在特定场景下按预设的方式工作。打个比方AI 编程助手本身像一个刚入职的聪明新人通用能力强但不懂你们公司的具体规矩。skills 就是你写给它的岗位操作手册遇到什么任务、按什么流程走、调用哪些工具、输出什么格式全都写清楚。它不需要你每次重新解释只要触发对应场景就自动按手册执行。这套机制解决的核心痛点是重复性指令的沉淀问题。没有 skills 的时候你每次让 AI 做代码审查、写单元测试、生成接口文档都得把要求重新描述一遍措辞稍有不同结果就飘。有了 skills这些要求变成文件一次写好、反复调用输出稳定性大幅提升。适合读这篇内容的人大致分三类一是刚接触 Claude Code、还在摸索怎么让它听话的新手二是已经用了一段时间、但每次都要重复交代背景的中级用户三是想把自己团队的开发规范固化成 AI 可执行资产的工程师或技术负责人。不管你在哪一层下面这些内容都能对上号。需要先说明一点skills 的具体实现细节在不同工具、不同版本间有差异本文讲的是通用思路和常见实践具体到你的环境以官方文档为准。但底层逻辑是相通的理解了就不容易迷路。2. SKILL.md 的骨架一个技能文件里到底装了什么2.1 为什么是 Markdown 而不是配置文件很多人第一反应会问既然是给程序读的为什么不用 JSON 或 YAML 这种结构化格式反而用 Markdown这个问题问到点子上了。原因在于 skills 的消费方是大语言模型不是传统解析器。模型对自然语言的理解能力远强于对严格语法的解析能力。用 Markdown 写你可以用标题分层、用列表列步骤、用代码块给示例模型读起来上下文清晰人读起来也舒服。如果硬用 JSON光是转义和嵌套就能把人逼疯而且模型对深层嵌套结构的理解反而不如平铺的自然语言。Markdown 还有一个隐性优势它天然适合版本管理。diff 出来一目了然谁改了哪句话、加了哪个步骤代码审查时看得清清楚楚。这对团队协作场景特别重要。2.2 一个技能文件的典型组成虽然不同工具的字段命名有出入但一个完整的技能描述文件通常包含这几块内容我用表格对照说明组成块作用常见写法名称与描述告诉系统这个技能叫什么、什么时候该用它顶部元信息或一级标题触发条件明确什么场景下激活这个技能当用户要求……时执行步骤具体怎么做分步骤列出有序列表输入输出约定需要什么信息、产出什么格式参数说明 示例边界与禁忌什么不能做、什么情况要停下来问注意事项段落参考示例一两个正例帮模型对齐预期代码块或对话示例这里最关键的是触发条件和边界与禁忌两块恰恰是新手最容易忽略的。很多人写技能只写怎么做不写什么时候做和什么时候别做结果模型在不该用的时候乱用或者该用的时候没反应。2.3 描述文字的颗粒度怎么把握写技能描述时颗粒度是个反复要权衡的问题。写太粗模型自由发挥空间大输出不稳定写太细又变成死板的脚本失去 AI 的灵活性。我的经验是流程性内容写细判断性内容写粗。比如先读取文件、再提取函数签名、最后生成文档这种步骤写细一点没关系反正顺序是固定的。但根据代码复杂度决定是否拆分这种判断就别写死阈值给个方向让模型自己权衡。举个具体的反例。有人写技能时规定如果函数超过 50 行就拆分结果遇到一个 51 行但逻辑紧密的函数模型硬拆反而破坏了可读性。更好的写法是关注函数职责是否单一行数只是参考信号之一。把判断权交还给模型同时给出判断维度这才是技能描述该有的样子。3. 触发机制技能是怎么被叫醒的3.1 显式调用与隐式匹配的区别技能被激活的方式大致分两种。一种是显式调用你直接说用 XX 技能处理这个模型明确知道要调用哪个。另一种是隐式匹配你只是描述任务系统根据技能描述里的触发条件自动判断该用哪个。显式调用稳定但需要你记住技能名字用起来有负担。隐式匹配省事但对技能描述的触发条件要求很高——写得不清楚模型就匹配不上或者匹配到错误的技能。实际使用中我建议关键流程用显式辅助能力用隐式。比如代码发布这种一步错步步错的流程显式调用确保万无一失。而像帮我看看这段代码有没有明显问题这种日常小任务交给隐式匹配就够了没必要每次都点名。3.2 触发条件写不好的三种典型症状症状一技能从不触发。你写了个技能但用的时候模型完全不理。八成是触发条件写得太窄或者用了模型不敏感的词。解决办法是把触发条件往宽了写多列几个同义场景。症状二技能乱触发。你只想让它处理 A 场景结果 B、C、D 场景它都往上套。这通常是触发条件写得太泛或者技能描述里出现了太多通用词。收窄描述把不相关的场景明确排除掉。症状三多个技能抢触发。你写了两个技能触发条件有重叠模型不知道该用哪个。这时候要么合并技能要么在描述里写清楚优先级和适用边界。提示调试触发问题时可以故意构造几个边界场景去测试看模型的实际反应比盯着描述文字空想有效得多。3.3 一个触发条件的具体写法对比光说理论太虚直接看对比。下面是一个生成接口文档技能的触发条件两种写法写法 A太窄当用户说生成接口文档时触发。写法 B合理当用户要求为某个 API、接口、endpoint 生成文档 或要求整理请求参数、响应结构、错误码说明时触发。 不适用于生成数据库表结构文档、生成前端组件文档。写法 B 覆盖了同义表达同时用不适用于划清了边界。实测下来B 的触发准确率明显高于 A。这个技巧在写任何技能时都适用正向列举 反向排除双管齐下。4. 从零写一个技能完整流程拆解4.1 先想清楚这个技能解决什么重复劳动动手写之前先问自己一个问题这个技能要替代的是哪段重复劳动如果答不上来说明还没到写技能的时候。好的技能候选通常满足三个特征高频经常要做、稳定每次做法基本一致、有明确产出做完有个可检验的结果。比如把一段 SQL 转成对应的 ORM 查询代码就符合而帮我思考一下架构就不适合做成技能因为太开放没有稳定产出。我见过有人一上来就想写个万能编程助手技能结果写了几百行模型根本用不明白。技能要小而专一个技能干好一件事比一个大而全的技能有用得多。4.2 起草技能文件的实操顺序确定要写什么之后按这个顺序起草先写触发条件。明确什么时候用、什么时候不用这是地基。再写执行步骤。把你自己做这件事的流程拆成步骤一步一句别合并。补输入输出约定。需要用户提供什么、最终产出什么格式写清楚。加边界与禁忌。哪些情况要停下来问、哪些操作绝对不能做。最后放示例。一个正例足够多了反而干扰。这个顺序的好处是每一步都建立在前一步的基础上不会写着写着跑偏。很多人习惯先写步骤最后才想触发条件结果发现步骤和触发场景对不上返工。4.3 步骤描述里的意图比动作更重要写执行步骤时新手容易写成纯动作流水账读取文件、解析、输出。这种写法模型能执行但遇到变体就懵。更好的做法是动作 意图。比如不写读取文件而写读取目标文件目的是获取完整的函数定义注意不要遗漏被注释掉的代码块。多了半句意图说明模型在遇到边界情况时就知道该怎么权衡。这个技巧来自一个教训。我曾经写了个代码重构技能步骤里只写提取重复代码结果模型把两段看起来像、实际语义不同的代码也合并了引入 bug。后来改成提取语义等价的重复代码判断等价性时优先看逻辑而非字面相似度问题就没了。意图描述是给模型的判断依据不是废话。4.4 写完之后的验证方法技能写完不能直接用得验证。我的验证分三步第一步正例测试。构造一个典型场景看技能是否触发、执行是否符合预期。第二步反例测试。构造一个不该触发的场景看技能是否安分。第三步边界测试。构造一个模棱两可的场景看模型怎么处理据此调整描述。这三步走下来基本能发现大部分问题。别嫌麻烦技能是要反复用的前期多花十分钟调试后期省下的是几十次重复解释。5. 技能库的组织与复用别让技能变成新的混乱5.1 技能多了之后怎么分类写了两三个技能时随便放哪都行。写到十几个就得考虑分类了。常见的分类维度有按功能域代码类、文档类、数据类、按使用频率高频、低频、按团队归属通用、某项目专用。我倾向于按功能域分因为找技能时人脑是按我要干什么检索的不是按这个技能多常用检索的。目录结构大致长这样skills/ code/ review.md refactor.md docs/ api-doc.md changelog.md data/ sql-convert.md简单直接一眼能找到。别搞太深的嵌套三层以上就开始烦了。5.2 技能之间的依赖与冲突技能不是孤立的。有的技能会调用另一个技能的能力有的技能之间触发条件重叠。这时候要处理好依赖和冲突。依赖关系建议显式声明。在技能描述里写一句本技能依赖 XX 技能的输出格式模型就知道要先确保那个技能可用。冲突关系则通过边界排除解决在各自的不适用于里写清楚。有个容易踩的坑两个技能都定义了同名的输出格式但格式细节不一致模型混用后产出四不像。解决办法是把公共格式抽出来单独定义两个技能都引用它而不是各写各的。5.3 版本管理与团队共享技能文件既然是文本就该纳入版本管理。每次修改都提交写清楚改了什么、为什么改。这样出问题时能回溯团队协作时也能看到演进过程。团队共享时建议维护一个技能索引文件列出所有可用技能、各自用途、维护人。新人进来先看索引比一个个翻文件高效得多。索引不用花哨一个表格就够技能名用途维护人最近更新code-review代码审查张三2024-XXapi-doc接口文档生成李四2024-XX这个表格看着简单但能省下大量这个技能谁写的、还能不能用的沟通成本。6. 实战中踩过的坑与排查思路6.1 技能不生效的完整排查链路技能写了但没反应这是最高频的问题。别急着重写按这个链路排查第一确认文件位置对不对。不同工具对技能文件的存放路径有要求放错地方系统根本扫不到。先查文档确认路径。第二确认文件格式对不对。Markdown 语法错误、编码问题都可能导致解析失败。用纯文本编辑器打开看看有没有乱码。第三确认触发条件是否匹配。把你实际说的话和技能里写的触发条件逐字对比看差在哪。经常是用户说的词和技能里写的词对不上。第四确认是否有更高优先级的技能拦截。如果同时有多个技能可能触发检查是不是被别的技能抢了。第五看日志。多数工具会输出技能匹配的日志直接看系统认为该用哪个技能比猜快得多。这个链路我走过很多次八成的问题在前三步就能定位。剩下两成看日志基本能解决。6.2 输出不稳定的三种归因技能触发了但每次输出质量参差不齐这也是常见困扰。归因下来无非三种描述模糊。技能里用了适当合理尽量这类词模型每次理解都不一样。解决办法是把模糊词替换成可判断的标准或者明确说明由模型根据上下文判断。示例不足或示例误导。只给一个示例模型可能过度拟合示例本身有瑕疵模型会学坏。建议给一到两个高质量示例确保示例本身经得起推敲。上下文干扰。当前对话里其他内容影响了模型判断。这种情况可以在技能里加一句忽略与本次任务无关的历史上下文帮模型聚焦。6.3 一个真实的排查案例有次我写了个生成单元测试的技能触发正常但生成的测试有时覆盖率高、有时只测了主流程。排查后发现问题出在步骤描述里写了为关键函数生成测试但关键没定义。模型有时理解为所有公开函数有时理解为核心业务函数。修改方案是把关键替换成明确标准为所有导出函数生成测试内部辅助函数若包含复杂逻辑也需覆盖。改完之后输出就稳定了。这个案例说明技能描述里的每个形容词都可能是隐患能量化就量化不能量化就明确判断维度。7. 进阶玩法让技能组合出更大价值7.1 技能链把多个技能串成工作流单个技能解决单点问题把多个技能串起来就能解决流程问题。比如代码审查 → 生成修复建议 → 自动应用修复 → 生成变更说明这条链每个环节一个技能串起来就是完整的代码维护流程。串链的关键是接口对齐。上一个技能的输出格式要正好是下一个技能的输入格式。这需要在设计技能时就考虑好上下游或者后期做格式适配。7.2 参数化技能一个技能应对多种场景有些技能场景相似但细节不同没必要写多个做成参数化即可。比如生成文档技能通过参数区分是生成 API 文档还是模块文档共用大部分逻辑只在输出格式上分叉。参数化的好处是维护成本低改一处全生效。坏处是描述会变复杂触发判断难度上升。权衡下来场景差异小于三成时参数化大于三成时拆开写这是我摸索出的经验线。7.3 技能的自省与迭代技能不是写完就完事要定期回顾。我习惯每个月翻一遍自己的技能库看哪些很久没用可能该删、哪些经常出问题该改、哪些场景变了该更新。迭代时保留修改记录写清楚每次改动的动机。过几个月回头看这些记录能帮你回忆起当时的思考避免重复踩坑。技能库就像代码库需要持续维护放着不管就会腐烂。8. 关于学习路径的一点个人体会回到热搜词里那个问题——如何学习 skills。我的看法是这东西没法纯靠看文档学会必须动手写。看十篇教程不如自己写一个技能、踩一次坑、改一版。入门路径我建议这样走先照着别人的技能改一个理解结构然后从自己最高频的重复劳动入手写第一个原创技能跑通之后再尝试写第二个、第三个慢慢形成自己的技能库。过程中遇到问题优先看日志、做对比测试而不是到处问人。还有个心态问题。很多人写技能追求一步到位写一个完美的。实际上技能是迭代出来的第一版能用就行后面根据实际使用慢慢打磨。我最早的几个技能现在回头看写得很粗糙但正是它们让我理解了这套机制才有了后面更成熟的版本。技能这东西本质是把你脑子里的隐性经验显性化。写的过程本身就是一次对自己工作方式的梳理。写得越多你会越清楚自己到底在重复做什么、哪些环节可以固化、哪些必须保留灵活性。这个认知比技能本身更有价值。
