你有没有过这种经历明明给 AI 助手写了一大段提示词它还是会在关键步骤上犯迷糊或者在错误的场景里乱用规则我试过把一整本操作手册直接贴进对话里结果模型要么记不住重点要么把不该动的文件也翻出来改一遍。后来我开始认真研究 skill 这套东西——把某个领域的做事方法打包成一份结构化指令文件让 AI 在遇到对应场景时自动加载执行——整体效率才算真正提起来了。这篇文章要聊的不是某个具体 skill 怎么写而是怎么“稳定地”写出一批高质量 skill。核心观点很直接写 skill 不是写作文而是一个工程过程需要方法抽象、流程设计、测试反馈和复盘迭代。我会把整个创建流程拆成五个阶段每个阶段给出可操作的动作最后附上一份 Review 清单你可以直接抄走当检查表用。无论你是刚接触 AI 编码工具的新手还是已经在维护几十个 skill 的老手这套流程都能帮你在下一个 skill 上少走弯路。1. 内容整体设计与思路拆解1.1 skill 到底是什么先定义一下省得后面理解跑偏。skill 在当前各类 AI 编程助手和 Agent 工具里本质上是一组“在特定场景下如何完成任务”的指令包。它通常以 Markdown 文件或目录形式存在里面写清楚触发条件、执行步骤、约束规则、参考示例等内容。当对话或任务进入对应场景模型会读取这个 skill按图索骥地执行。你可以把它理解为一张菜谱不是所有菜都适合拿一张菜谱硬套但只要有明确的菜系和目标菜谱就比“凭感觉放调料”稳定得多。skill 解决的核心痛点是把“这次问 AI 它刚好答对了”变成“这个场景下 AI 每次都能按约定执行”。1.2 为什么要有一整套方法论很多人写 skill 的方式是遇到一个需求打开编辑器想到哪写到哪写完丢给模型试一下效果不好就继续堆字。这种方式在小规模、一次性场景里能糊弄过去但一旦 skill 数量变多、使用频率变高问题就全出来了。我见过最典型的情况一个项目里攒了二十几个 skill有的专门管代码审查有的管日志分析结果遇到一个“同时需要审查和安全检查”的任务两个 skill 连连看一样叠加加载指令互相打架模型反而不知道该听谁的。还有一种情况更常见——skill 写得很“情绪化”里面全是“仔细处理”“合理优化”这种模糊词模型执行起来全凭猜输出质量完全不可控。方法论要解决的就是这三件事可复用、可传授、可维护。可复用意味着同一个 skill 换一个项目、换一台机器依然能稳定工作可传授意味着别人拿到你的 skill不需要你解释三遍就能看懂并继续维护可维护意味着出问题时你能快速定位是规则问题、触发问题还是流程问题而不是从头读一遍整个文件靠猜。1.3 方法抽象的三个核心视角做方法抽象之前先抓住三个核心视角。第一是“通用范式提炼”把你平时处理某类任务的过程从直觉和临时判断中抽出来变成一组明确、可检查的步骤。第二是“函数式思维”把 skill 想象成一个函数输入是任务描述和场景上下文输出是产物或决策内部的规则和步骤就是函数体。设计时始终问自己输入边界是什么外部依赖是什么输出怎么验证第三是“最小可用范围”。这是最容易忽略的一点。很多人一上来就想写一个“万能 skill”覆盖所有情况结果规则堆到几千行模型每次加载都很吃力而且很容易在边缘场景里给出错误判断。好的 skill 应该像一把手术刀而不是瑞士军刀先锁死一个明确任务范围把核心流程打磨稳再考虑扩展。2. 核心细节解析与实操要点2.1 先划边界输入触发条件与输出验收标准开始动手写任何内容之前先把两个边界想清楚什么情况下这个 skill 应该被激活以及完成任务后什么样的输出可以被接受。触发条件一定要具体。很多 skill 写得含糊比如“当用户需要分析代码时使用”这句话几乎毫无约束力——代码分析有复杂度分析、性能分析、安全分析、风格分析模型根本不知道你说的是哪种。更合理的写法是给出一组可判断的特征词和场景描述比如“当用户提到 CPU 占用率、接口延迟、慢查询或要求排查性能瓶颈时激活性能分析流程”。这样模型才能准确把任务对号入座。输出验收标准同样关键。你在 Review 一个 skill 时第一件事不是读内容而是问自己如果模型严格按照这个 skill 执行产出的东西是不是一眼能看出合格还是不合格如果答案模棱两可说明验收标准缺失。比如“生成一份代码审查报告”标准可以细化成“必须列出问题文件、问题行号、严重程度、修改建议”四项缺一项就算不合格。标准写得越可检查模型执行的一致性就越高。2.2 抽象公共步骤从具体流程到指令模板假设你要写一个“日志分析 skill”你脑海里肯定已经有了完整流程先看日志格式、再过滤错误级别、按时间窗口聚合、找异常模式、给结论。问题在于这套流程在你脑子里是“下意识”的你很难原样交给模型。方法抽象做的就是把下意识变成显式指令。一个很好用的方法把你在类似任务里的操作过程录下来或用文字复盘出来然后逐条问自己三个问题——这一步是不是每次都必须做这一步的输入是什么、输出是什么如果缺少这一步对最终结果有多大影响凡是回答“不是每次都需要”的步骤降级为条件分支凡是“不执行就严重影响结果”的步骤列为必须步骤其余属于可选增强项。做完这轮筛选你得到的就不是一段描述性的流程而是一张带优先级和条件分支的决策表。把这个决策表转换为指令文本就是 skill 的主要内容。这个过程我称之为“从感性流程到理性模板”的转换也是方法抽象最核心的一步判断。2.3 分层编写把规则、知识和执行动作拆开写 skill 的时候最容易犯的一个错误是“一锅炖”。判断规则、背景知识、执行步骤、输出格式全部揉在一个长文档里模型读起来费劲维护起来更痛苦。我的习惯是至少拆成四层meta 管理层、执行层、知识层、自检层。meta 管理层放在文件头部记录 skill 的名称、触发条件、适用范围、作者、版本号。这部分的价值在于让模型快速判断“要不要加载这个 skill”也方便你在多 skill 共存时排查加载冲突。执行层是核心按顺序列出处理任务的具体步骤每一步都要给出“做什么”和“怎么判断结果”。知识层是用来支撑执行层的背景资料比如代码仓库结构、团队规范、常用命令这些内容如果直接塞进执行步骤里会让主线变得很乱。自检层是输出前必须过一遍的检查项相当于 skill 给自己的一轮 code review。分层带来的直接好处有两个。一是模型执行时可以按需读取不会因为上下文太长而丢失关键指令二是你自己复盘时能快速定位问题命中了哪一层不需要从头到尾通读全文。2.4 skill 文件的最小骨架怎么写才叫“结构完整”无论你用什么工具管理 skill一个结构完整的 skill 文件通常都长这样--- name: 性能瓶颈排查 description: 当用户反馈接口慢、CPU 高或数据库延迟时执行系统化性能排查。 version: 1.0.0 triggers: - 接口延迟 - CPU 占用率 - 慢查询 --- # 目标 在 30 分钟内定位性能瓶颈根因输出可复现的优化建议。 # 执行步骤 1. 收集基础指标CPU、内存、I/O、网络 2. 定位热点进程或接口 3. 按调用链逐层下钻 4. 对比近期变更排除回归影响 # 常用命令与知识 - top -Hp pid查看线程级 CPU 占用 - 本地压测命令参考 docs/benchmark.md # 输出格式 - 问题现象简述 - 根因分析 - 优化建议按优先级排序 # 自检清单 - 是否已覆盖所有采集指标 - 根因是否有数据支撑 - 建议是否可执行且不会引入新问题这个骨架里每一个 section 都有明确用途缺一个都会影响效果。尤其要注意 description 和 triggers 这两块它们是模型判断“要不要加载这个 skill”的决定性信息多花点字把触发条件写清楚比正文多写十行废话更有价值。3. 实操过程与核心环节实现3.1 阶段一定义危与机明确这个 skill 到底为谁解决什么问题在写任何内容之前先做一次“定义危与机”的练习。危是什么没有这个 skill用户会遇到什么具体麻烦机是什么有了这个 skill能做到什么程度我做一个 skill 前通常会在项目里专门开一个文档记录这些信息并且要求自己用三句话就能说清楚这个 skill 服务的对象是谁、解决的主要矛盾是什么、成功的标志是什么。别小看这三句话很多 skill 做着做着就变形就是因为原始目标和最终实现越来越远。除此之外还要定义“这个 skill 不做的事”。一个只做日志分析的 skill如果任务里带着“顺便部署上线”它应该明确拒绝执行或者提示用户切换到对应 skill而不是硬着头皮往下做。写清楚边界能避免很多误触发和误操作的问题。3.2 阶段二采集与提炼把散落经验变成结构化规则这一步的核心动作是“做过的事全部记下来”。你在项目里处理过 20 次部署问题每次你都知道要先看哪几个地方、按什么顺序检查、哪些情况可以直接忽略但这些全在你脑子里模型根本不知道。你需要把这些经验刻意输出成规则。操作方法先列出你做这类任务的 5 到 10 个典型案例给每个案例写清楚当时的背景、操作步骤、结果和踩过的坑。然后逐条对比案例之间有没有共同规律把共同点提炼成通用步骤把不同点整理成条件分支。最后把提炼结果按“必须做 / 条件做 / 禁止做”三类归档形成规则清单。有一个很关键的点提炼规则时不要只写“做什么”还要写“为什么”。模型并不是死记硬背的工具它需要理解规则背后的意图才能在边缘情况里做合理推断。比如“不要直接在生产环境执行 DDL 修改表结构”后面紧跟一句“生产变更必须走工单系统”和“避免未评审操作导致数据不可恢复”模型在处理类似问题时就会更有分寸感。3.3 阶段三分层编写与配置搭出可直接复用的目录结构规则提炼完之后就开始落地成文件了。我建议一个 skill 不要只做一个大文件而是按目录组织。一个比较稳的目录结构长这样my-skill/ ├── SKILL.md # 入口文件含 meta 信息和执行总纲 ├── rules/ │ ├── must.md # 必须执行的硬性规则 │ ├── conditions.md # 条件触发规则 │ └── forbidden.md # 禁止项清单 ├── templates/ │ ├── report.md # 输出报告模板 │ └── checklist.md # 执行过程检查表 └── references/ ├── commands.md # 常用命令速查 └── knowledge.md # 背景知识库这种组织方式有两个好处一是模型在实际执行时可以直接定位到 rules/must.md 去检索硬性规则不需要在几万字的大文件里翻二是你自己维护时新增一条“禁止项”只改 forbidden.md不会影响其他内容。配置过程中还要注意文件中引用的外部路径。比如 commands.md 里写了某个脚本的位置最好用相对路径或者写明“此脚本由 skill 初始化时自动生成”避免换一台机器后路径失效。我踩过这个坑原来写的分析脚本用的是本地绝对路径文档发给同事后他跑了半天一直报错后来统一改成了项目内相对路径才解决。3.4 阶段四测试迭代小场景验证比大范围铺开更靠谱写完 skill 后别急着大规模投入使用先找一个小范围、低风险的场景跑一遍。具体做法准备 3 到 5 个代表性测试用例覆盖正常场景、边界场景和失败场景各至少一个。正常场景用来验证主流程是否顺滑边界场景看 skill 在极端输入下是否还能守住规则失败场景看 skill 遇到解决不了的问题时会不会给出合理的降级处理或拒绝执行。测试过程中我建议记录两个东西一是模型的实际输出二是你期望的输出两者不一致的地方就是需要修正的规则。很多人在这一步偷懒觉得“差不多能用就行”结果 skill 上线后在一个奇怪的长尾场景里翻车反而花更多时间擦屁股。迭代的时候一次只改一个变量。如果你同时改了触发条件、执行步骤和输出格式模型效果变差了你根本不知道是哪里出了问题。我现在的习惯是每次改动前先用一个版本号记录改动原因和改动点方便随时回滚到上一个稳定版本。3.5 阶段五沉淀复盘把维护成本转化成长期资产测试通过之后skill 就算正式上线了但这不代表工作结束。以我的经验每个 skill 用两周到一个月后一定会冒出一些当初设计时没想到的情况可能是触发条件太窄导致漏加载也可能是知识库里的内容已经过时需要补充新命令。这时候复盘很重要。我会在项目的 docs/skills-review 目录下给每个 skill 单独建一个复盘文档记录上线后的使用次数、典型问题、用户反馈和待改进项。Review 的频率不用太高每个月过一遍就行重点回答三个问题这个 skill 还在解决核心问题吗执行过程中有没有反复出现的偏差下一次优化应该优先改哪个部分复盘不是走形式它是把维护成本变成长期资产的关键一步。做了复盘你才能越来越懂“什么规则有效、什么话术是废话”下一批 skill 的质量也会水涨船高。4. 常见问题与排查技巧实录4.1 从“感觉不对”到“查得动”调试输出法skill 用起来“感觉不对”是最难排查的情况因为它没有硬报错模型也能正常返回内容但结果就是不合预期。面对这种情况我推荐一个比较实用的排查技巧调试输出法。做法很简单在 skill 里显式要求模型在回答开头或末尾附上“本次执行依据”也就是让它自己说明加载了哪些规则、走了哪些分支、哪几条规则对当前输出影响最大。这个附加信息看起来有点多余但排查问题的时候特别有用。你能直接看到模型有没有读到你期望的规则有没有被其他 skill 的规则干扰。我自己的项目里给每个 skill 都内置了一个 debug 开关通过环境变量控制默认关闭。出问题时打开开关跑一次观察输出里的“执行依据”基本上五分钟内就能定位是触发条件写窄了、规则有歧义还是跟其他 skill 冲突。这比盲猜高效得多。4.2 常见失败的四种“死法”和对应解法我用过和写过的 skill 多了总结下来失败模式基本就那么几种对号入座就能解决。第一种是“技能打架”。一个任务同时触发多个 skill规则互相矛盾。解法是在 meta 管理层明确每个 skill 的适用范围并给规则加优先级标注。冲突时高优先级的覆盖低优先级这一条写清楚能省很多事。第二种是“上下文超载”。skill 内容太长模型读不完或者读了忘。解决思路不是删除内容而是分层拆分让模型按需加载。主文件里只放骨架细节全部丢到 references 子目录由执行步骤指定“这一步读取 references/commands.md 获取命令”。第三种是“路径写死”。skill 里引用的文件或命令在换机器后失效。解法有两层一是统一使用相对路径二是让 skill 在初始化时先检查环境依赖缺少哪个组件直接跳出提示而不是等到中间步骤才发现跑不通。第四种是“规则模糊”。这也最常见。规则里全是“精准定位”“全面分析”这种词模型不知道标准是什么。解法是在规则后面附上明确的检查项和成功标准比如“定位到具体文件与行号”比“精准定位”好使一百倍。4.3 一张速查表问题、现象、定位思路、解决办法症状描述可能原因定位思路解决方案skill 没被触发description 和 triggers 写得太泛检查入口文件加载记录确认“执行依据”里是否包含该 skill 名称用具体特征词重写 triggers缩小适用范围输出混乱、结构不固定输出格式没有约束或约束太弱观察输出是否多次出现不一致字段提供固定模板并用自检清单强制逐项检查执行步骤顺序不稳定步骤之间缺少依赖表达观察模型先做哪一步、后做哪一步在步骤里写明“上一步完成后”等顺序标记并说明原因与另一个 skill 规则冲突两个 skill 触发条件有重叠对照两个 skill 的 triggers 和禁止项明确优先级或在触发条件里排除对方场景换机器后执行失败路径或外部依赖失效查看报错信息中是否有路径相关提示改为相对路径并在入口文件写明前置依赖检查上下文太长影响效果单文件内容过多查看模型返回时是否遗漏后文规则按 rules / references 拆分主文件只保留执行骨架模型经常“忘了”做某一步步骤过多且无优先级检查规则是否按必须、条件、禁止分类重新分层必须步骤靠前并与输出自检绑定这张表不是标准答案但它覆盖了绝大多数我实际遇到过的失败场景。遇到新问题时先按这个框架归类再针对性地改规则比从头到尾读一遍 skill 再猜要高效得多。5. 附Review 清单可直接抄走5.1 先回答这 10 个问题再发布你的 skill正式上线或分享给别人之前卡住下面这 10 个问题一个个过这个 skill 的服务对象是谁是被 AI 使用还是被人类直接查阅什么情况下它会被加载触发条件能否用具体关键词描述它不做的事有哪些是否写清楚了边界完成任务后输出物怎么验收有没有可检查的合格标准执行步骤里有没有必须做、条件做、禁止做的分类每条规则是否解释了“为什么”而不只是“做什么”引用的路径、命令、外部文件是否在换环境后依然可用是否提供模板或检查表来约束输出格式出问题时模型有没有办法自检或提示降级处理版本号、改动记录、复盘文档是否齐全只要有一项回答“没有”或“不清楚”就说明 skill 还没到可以直接发布的状态。别嫌麻烦这 10 个问题帮我挡掉了至少一半的线上事故。5.2 逐项自检清单下面这份清单我建议打印出来或存成模板每写一个新 skill 就过一遍。说明一下这是一份通用的、供你自己做逐项验收用的工具不要把它当成 skill 内容塞给模型。检查维度具体检查项状态边界触发条件是否用具体特征词描述是 / 否边界适用和不适用范围是否明确是 / 否规则规则是否区分必须、条件、禁止是 / 否规则每条规则是否有“为什么”说明是 / 否步骤步骤是否有序号且依赖关系清楚是 / 否步骤关键条件分支是否覆盖主要异常路径是 / 否输出是否有固定模板或可检查的验收标准是 / 否输出自检清单是否在输出前强制触发是 / 否依赖路径、命令、外部文件在不同环境下是否可用是 / 否维护版本号、改动原因、复盘文档是否完整是 / 否5.3 上线后的维护习惯最后提一个维护上的小建议。不要觉得 skill 写完上线就进“维护期”了而是应该把每一次使用的异常反馈都当成下一次迭代的输入。我现在给自己定了一个很简单的规矩任何一个 skill如果连续两次在同类场景下表现不佳就必须停下来做一次完整复盘更新 Review 清单里对应的检查项如果一个月没被用到就认真考虑是触发条件太窄了还是这个需求本来就该由其他方式解决。复盘出来的新规则加进 skill 时可以做两件事巩固一是更新版本号并写清改动原因方便回滚二是定期把规则文件里已经不再生效的“旧知识”清理掉避免模型被过时的内容误导。我在实际项目中还发现把这份 Review 清单制度化比单独提升某个 skill 的质量更能带来整体效率的提升。因为清单本身就是一个方法论抽象帮你从“每个 skill 从头磨”变成“照着成熟流程生产”。如果你现在维护的 skill 数量超过三个我真的建议你把这份清单收起来下一个 skill 试一次感受一下差别。