写 skill 这件事我前后折腾了大半年从最早的“把所有规矩塞进一个 prompt”到后来慢慢形成一套稳定的创建和评审流程。中间踩过的坑实在太多最典型的就是辛辛苦苦写出来的 skill模型要么完全不触发要么执行起来自由发挥输出格式每次都不一样。后来我意识到一个问题——真正值钱的不是某一个 skill 本身而是“高效创建 skill 的方法”。这篇文章就是把这一套方法论完整拆开核心是方法抽象和流程化文末附上一份我每次交付前都会逐条过一遍的 Review 清单你可以直接拿去改。这套流程适合谁给 AI 助手沉淀可复用能力的开发者、正在整理团队 skill 规范的人以及那些已经写过不少 prompt 但总觉得“效果不稳定”的朋友。我会尽量少讲虚的多给可以直接落地的东西。1. 先想清楚skill 是什么方法论到底在解决什么问题1.1 skill 不是提示词模板是“可复用的行为契约”很多人对 skill 的理解停留在“一段写得很好的提示词”这是最大的误区。提示词解决的是“这一次对话怎么表现”skill 解决的是“这一类任务在任何一次对话里都按约定表现”。它更像是一份给模型看的行为契约什么情况触发你、你负责做什么、不做什么、按什么顺序做、输出成什么样子。举个例子一个“代码审查 skill”如果只是写一句“请你帮我审查这段代码”那它和普通提示词没有任何区别。一个真正可用的 skill至少要包含触发条件、边界说明、审查步骤、输出模板、反例提示。它把原本依赖用户现场描述需求的不确定性转变成了一套可以反复调用的固定流程。用户发一段 diff 过来模型就知道要按流程走而不是漫无边际地发挥。我一开始写 skill 也走过弯路把所有要求堆在一起结果模型读不完执行起来既慢又乱。后来我才总结出一个判断标准一个好的 skill应该像一份合格的操作手册而不是一篇论文。论文允许读者自由解读手册只能有一种执行方式。1.2 为什么大多数人的 skill 无效结合我给团队做 skill 规范的经验无效 skill 通常长这几个样子把 skill 写成百科全书场景覆盖过宽指令过长模型根本读不完重点没有明确的触发条件模型不知道什么时候该用用户也不知道怎么唤起只写了“要做什么”没写“做成什么样”没有输出模板模型每次给的格式都不同没有边界和降级路径输入一旦不完整模型就硬着头皮瞎编一次性写太多步骤希望模型同时完成风险分析、方案设计、代码实现、生成文档结果哪一步都做不深。这些问题的根源不是模型能力不够而是创建者没有把任务抽象成“模型能稳定执行的流程”。方法论要解决的恰恰是这件事。1.3 方法抽象的核心理念从单次交付到可复用资产“方法抽象”这个词听起来有点玄其实核心就一句话把你在一次任务里验证有效的经验提炼成可迁移、可复用、可评审的规则。同样一个经验放在某个具体 skill 里只能服务一个场景抽象出来之后就能服务一类场景。比如我写过很多审查类 skill——代码审查、文档审查、日志分析审查。做完第一个之后我发现它们共享同一套骨架都要求先明确对象范围再分维度检查最后用等级标记输出问题。这个骨架被抽象出来之后后面再写任何审查类 skill我只需要替换具体维度就够了效率至少翻一倍。这也是我为什么坚持把“创建 skill 的流程”本身当成一个 skill 来对待——它有骨架、有步骤、有输出标准、有 review 清单可以被复用和迭代。下面我就完整讲一遍这套流程。2. 动手写之前最重要的四步准备很多人的习惯是直接打开编辑器开始写写到一半发现需求根本没想清楚。我再三强调准备阶段花 15 分钟能省掉后期 3 小时的返工。这四步别跳。2.1 明确使用场景和用户意图开始写之前先用一句话回答这个问题这个 skill 是为“谁”在“什么场景”下解决“什么具体问题”这里的“谁”不只是用户还包括模型。同一个问题给新人用的 skill 和给资深工程师用的 skill写法完全不同。给新人的要步骤详细、给足示例给资深工程师的要直击要点、少废话。场景要具体到能画出一条用户输入的样例。比如“代码审查 skill”不能只写“审查代码”要写清楚用户可能粘贴一段 diff、可能给一个 MR 链接、可能直接问“这个变更有什么风险”。每一种入口都对应不同的处理方式。用户意图也要拆一下。同样是发来一段代码有人想听风险提示有人想让你直接改好有人只是想知道“这段代码会不会炸”。在准备阶段把常见的几种意图列出来写 skill 的时候你才知道哪个是主流程、哪个是分支。2.2 确定 skill 的边界与降级路径边界是大多数 skill 最容易忽略的部分。我见过太多 skill 从头到尾只写“要做什么”完全不写“不要做什么”结果模型把不相关的问题也接过来处理了。边界至少包括两层。第一层是触发边界哪些输入应该走这个 skill哪些输入应该礼貌地告诉用户“这不属于我的职责”。第二层是任务边界这个 skill 只做到哪一步为止哪些后续工作应该交给其他工具或其他 skill。降级路径同样重要。用户输入的信息不够怎么办模型必须补问、还是根据默认假设继续工具调用失败怎么办是要重试、换备用方案、还是直接返回部分结果这些如果不提前写明白模型遇到异常就会“自由发挥”而自由发挥恰恰是产出不稳定最大的来源。2.3 命名与触发策略命名这件事直接决定 skill 能不能被模型“想得起来”。我常用的规则是用“动词 对象”的结构例如 review-code、analyze-logs、draft-report。这样命名既清晰也方便模型在理解用户意图时快速关联。description 字段里要埋好用户在真实对话里会说的话。很多人写 description 像写论文摘要全是“提供全面的、专业的、深入的代码审查服务”但用户根本不会这么说话。用户会说“帮我看看这段代码”、“这个 PR 有问题吗”、“diff 帮我检查一下”。这些自然口语表达才是触发 skill 的关键词。触发策略还要考虑“不触发”的情况。description 里明确写出“只在用户提供代码或 diff 时触发日常闲聊不触发”能有效减少误触发。这一步很关键但很多人不写。2.4 定义输入、输出与状态流转输入和输出定义不清晰skill 写一半你就会发现模型开始自由发挥。输入方面明确这个 skill 需要哪几个关键信息哪些是必须的哪些是可选的哪些缺了可以直接补问。输出方面要给出结构模板最好是字段级定义。状态流转指的是任务的处理顺序。例如先接收输入再确认信息是否完整然后执行检查最后输出报告。流程类 skill 尤其需要状态流转的定义否则模型会跳步或者做了第一步就直接出结论。这一步做得好后面写指令体就会很顺因为你不是在“想办法描述”你只是在把已经定好的结构翻译成模型能读懂的语言。3. 核心实操从需求到可用 skill 的完整五步流程准备做完之后正式的写作流程我固定为五步起稿一句话需求、搭标准骨架、填指令体、配示例、测试迭代。下面每一步我都写清楚做法和理由。3.1 第一步用“一句话需求”起稿先不要写任何正文只写一句话。这一句话要同时包含触发场景和交付结果。例如“当用户提供合并请求或 diff 时按风险、逻辑、可读性、测试覆盖四个维度审查输出带 P0/P1/P2 等级标记的结构化报告。”这一句话写清楚后面所有步骤都不会跑偏。如果这句话写不出来说明需求没想透先回去做第二节的准备工作。如果一句话能写出来但超过三行说明范围太大了建议拆分。这一步的逻辑是用最少的文字锁住 skill 的核心定位后续所有细节都是在为这句话服务。方向对了细节才有意义。3.2 第二步搭标准骨架我所有 skill 都用同一套 YAML frontmatter 加 Markdown 指令体的结构这样方便批量管理和被模型稳定识别。下面是一个通用骨架--- name: review-code description: 当用户提供 Git 合并请求、diff 或代码片段时进行代码审查并输出结构化报告。日常闲聊不触发。 version: 1.0.0 trigger: - 用户粘贴 diff 或代码片段 - 用户提供 MR/GitLab PR 链接 - 用户明确要求“review 这段代码” out_of_scope: - 与代码审查无关的日常对话 - 没有提供任何代码上下文直接要求“随便看看” --- # 角色与目标 你是一个严格的代码审查助手目标是帮助用户提前发现变更中的风险。 # 处理流程 1. 确认输入判断是否包含可审查的代码或 diff。 - 信息不足时追问需要审查的具体文件或片段。 2. 分维度审查按 风险、逻辑、可读性、测试覆盖 四个维度逐项检查。 3. 输出报告按下方模板输出。 # 输出模板 ## 审查结论 总体评价一句话 ## 问题列表 | 等级 | 位置 | 问题描述 | 修改建议 | |------|------|----------|----------| 等级说明 - P0必须修复存在明显缺陷或安全隐患 - P1建议修复影响可维护性或存在潜在风险 - P2可选优化不影响功能 # 边界与降级 - 只做代码审查不负责直接修改代码。用户要求改码时提示可以切换到其他专用 skill。 - 没有代码上下文时不要臆测必须追问。 - 当 diff 过大时优先分析影响面最大的变更模块。这个骨架的每一段都有明确作用frontmatter 里的 description 和 trigger 负责被模型匹配out_of_scope 负责防误触处理流程负责约束执行顺序输出模板负责稳定格式边界与降级负责兜底。缺任何一个都会在某个环节出问题。3.3 第三步填充指令体时的写作技巧指令体不是越详细越好而是要“详细得刚刚好”。我用三个标准控制尺度动词明确、顺序清晰、例子具体。动词要明确。不要写“分析一下代码”要写“检查是否存在空指针风险”。不要写“优化一下表达”要写“将被动语态改为主动语态”。模型对动作性词汇的执行力远强于模糊判断。顺序要清晰。步骤数量控制在 5 到 9 步之间超过 9 步模型容易在中间丢步骤。每个步骤之间要有明确的先后逻辑最好用编号列表。如果某一步是条件分支要明确“在什么情况下走哪个分支”。例子要具体。一个例子胜过十句说明。至少给一个正例、一个反例。正例告诉模型“这么输出是对的”反例告诉模型“出现这种情况不要这么干”。我在写“日志分析 skill”的时候特意加了一个反例当日志中完全没有报错时不要为了凑数编造“潜在风险”如实写“未发现异常”即可。这个反例直接减少了 80% 的虚构问题。3.4 第四步配示例与测试迭代示例不是可选项是必选项。我建议每个 skill 至少配两组测试用例一组是标准输入验证主流程是否正常一组是边界输入验证降级路径是否生效。测试方法我比较推荐一个笨办法准备一个固定的测试文件里面放 10 条典型输入每次修改 skill 之后让模型按这些输入跑一遍对照输出检查格式符合率和内容准确率。别凭感觉“好像差不多”要可量化。格式符合率低就补输出模板内容准确率低就补指令细节问题出现在哪就改哪。多模型交叉验证也值得做。同一份 skill在不同的模型上表现通常有差异。有的模型解读指令能力更强有的则容易遗漏细节。如果你的 skill 要跨模型使用至少找两个主流模型各跑一遍然后把差异点写成补充说明加到指令里。这一步不要怕麻烦迭代的次数越多skill 的质量越稳。我目前的状态是新写的 skill 至少要迭代 3 版才敢进公共库第 1 版永远只是草稿。4. Review 清单每次交付前逐条过一遍这部分是全文的落点。所有方法论最终都要落到这份清单上。我在团队内部推行过把花在评审上的时间从半小时压缩到十分钟同时评审出的问题反而更全。建议你把这一节收藏每次写完之后对照着过一遍。4.1 方向与边界检查这组检查先确认“方向对不对”方向错了后面全是白写。[ ] 能否用一句话说清楚这个 skill 解决的具体问题[ ] 触发条件是否覆盖了用户主要的表达方式是否有自然口语关键词[ ] 是否明确了不触发的情况是否存在误触发风险[ ] out_of_scope 里是否写清了“这个 skill 不负责什么”[ ] 是否与现有 skill 存在职责重叠如果有是否已说明由哪个 skill 优先处理4.2 可执行性检查这组检查确认“模型能不能照做”。[ ] 指令是否使用明确动作词汇而不是模糊判断[ ] 处理步骤是否控制在 5-9 步[ ] 步骤顺序是否严格反映真实执行逻辑[ ] 是否提供了结构化输出模板而非只做文字描述[ ] 是否至少包含一个正例和一个反例4.3 鲁棒性与降级检查这组检查确认“异常情况下模型会不会崩”。[ ] 当用户输入信息不完整时是否明确了追问策略[ ] 当任务超出边界时是否定义了拒绝方式[ ] 当工具或中间环节失败时是否提供了备选路径[ ] 是否明确要求模型在证据不足时“如实说明未知”而不是编造答案[ ] 是否考虑了超长输入的截断或优先级处理4.4 可维护性检查这组检查确认“这个 skill 以后还好不好改、能不能复用”。[ ] 是否填写了版本号并在修改后递增[ ] 命名是否符合“动词 对象”的规范方便检索[ ] description 是否包含会出现在真实对话中的关键表达[ ] 指令体是否避免了与模型内置能力的重复浪费[ ] 是否删掉了所有“为了让内容专业而堆砌的废话”5. 常见问题与排查技巧实录5.1 模型不触发 skill这是被问得最多的问题。模型不触发九成是 description 和 trigger 写得不对。检查两件事第一description 里有没有用户真实会说的话第二这些表达是不是太书面化。比如 description 里写“当用户提交一个 product requirement for code review”用户实际说的是“帮我看看这段改的有没有问题”模型匹配不上自然就不触发。把后者加到 trigger 里触发率立刻提上来。还有一种情况是多个 skill 的触发条件互相覆盖模型不知道该用哪个。解决办法是给每个 skill 的 description 尾部加一句“此任务只适用于 XX 场景其他场景请忽略本技能”。5.2 模型执行时自由发挥、输出不稳定输出不稳定要么没给模板要么给了一个模板但没强调“必须”。我现在的做法是输出模板部分直接用“必须按以下结构输出不要额外添加内容”的强约束句式。同时给一个精简的示例输出模型会照着格式模仿。另一个常见原因是“要模型做的步骤太多”。一次让它完成五个目标结果模型每一步都浅尝辄止。解决办法是拆分如果五个目标之间存在先后依赖改成串联式流程如果五个目标相互独立拆成多个 skill。5.3 指令写在 skill 里但模型执行时忽略这个问题排查起来稍微复杂一点。首先看指令位置是不是太靠后。模型对长篇内容的注意力会衰减重要的规则尽量放在前面三分之一。其次看指令是不是和模型默认行为冲突。比如模型天生倾向于帮忙你写“不要修改代码”它可能在用户请求时依然尝试。这时候错误提示要更主动比如改成“用户要求修改代码时明确告知本技能不支持修改并建议切换技能”。第三可能是示例不够。模型在无法确定你的意图时会自行推断。关键规则前后各放一个正例规则被遵循的概率会高出很多。5.4 跨模型使用效果差异大同一个 skill在不同的模型上效果不同这是现实。我的处理办法是把指令里所有“依赖推理能力”的模糊描述改成“依赖流程编排”的明确步骤。比如“分析这个请求的安全性”是模糊描述改成“第一步列出涉及的函数、第二步检查输入是否来自未经过滤的入口、第三步确认是否缺少访问控制”就是流程编排。流程感越强对模型推理能力的依赖越低跨模型稳定性自然越好。另外一个细节不要在 skill 里使用模型容易误判的“高级词汇”。比如“优雅”“健壮”“充分”这类程度词不同模型的解读差异很大。改成可验证的标准比如“覆盖正常路径、异常路径、边界条件三类输入”模型执行起来就不会跑偏。我自己现在写 skill 的第一步永远是先写“失败场景”这个 skill 在什么情况下会失败失败后模型应该怎么兜底。把这个想清楚再动笔后面几乎不需要大改。你如果刚开始搭建自己的 skill 流程可以从复制这份 Review 清单开始先用它评审一个你已经写完的 skill你会发现很多之前没注意到的问题。经历几轮之后再按自己的习惯调整这套方法论就会真正变成你的东西。