SKILL.md写作指南：从提示词模板到可复用技能规范

很多人拿到 SKILL.md 的第一反应是把原来写在系统提示词里的那段“你是一个……请帮我做……”直接搬进来改个标题就完事。我不止一次在代码评审里看到这样的技能文件整篇都是角色扮演式的语气描述真正的执行流程、边界条件、输出约束一概没有。你要是也这样写SKILL.md 的核心价值基本就被浪费了——它不只是一张“人设卡”而是一份可以被调度器识别、按需加载、稳定复用的技能规范。这篇文章我想从几个层面把这件事掰开揉碎先讲清楚 SKILL.md 和提示词模板的本质差异再拆解一个技能目录应该怎么搭、字段怎么写然后我会拿一个“代码评审技能”做完整实战示范最后把部署之后最常见的故障和排查思路也一并给你。适合正在做 Agent 开发、智能体项目或者想把某个固定工作流沉淀成可复用技能的开发者参考。1. 先纠正一个观念SKILL.md 的读者不是人是 Agent 的调度器1.1 提示词模板解决的是“开场白”技能解决的是“执行”提示词模板的核心作用是在对话开始时给模型一个明确的角色和任务上下文。它的生命周期很短通常只对当前这轮会话生效。你写一个“你是一位资深文案专家请帮我写一篇公众号文章”的模板下次对话想用同样的能力还得再复制一遍。SKILL.md 解决的则是“执行”问题。它的存在不是为了开启一段对话而是让 Agent 在运行过程中能自己发现“这项任务我有现成的处理方式”然后主动去加载对应的技能目录按照里面的流程、规则、输出格式完成工作。换句话说提示词模板是被动的技能是主动的。我在实际项目里的感受是提示词模板适合一次性任务SKILL.md 适合高频复用的流程。比如“帮我把一段口语录音整理成会议纪要”这种每周都要做十几次的事情如果每次都用提示词模板去指挥模型不仅 Token 浪费严重而且输出质量完全取决于当天模型的状态。沉淀成技能之后只要触发条件满足Agent 自己就会去加载技能目录每一步该做什么、格式什么样全部固化下来输出稳定得多。1.2 技能目录是 Agent 自己会去“翻阅”的说明书一个合格的 SKILL.md读者是 Agent 的调度器和模型本身而不是人。这一点怎么理解目前主流 Agent 框架普遍把技能定义为一个目录目录下的 SKILL.md 是这个技能的入口文档。调度器在决定“当前任务要不要调用某个技能”时主要依据的是 SKILL.md 里的 description 字段模型在执行技能时读取的是正文里的指令、范例和边界。整个过程里人类是不参与阅读的。所以很多“写给人看”的写法就变得非常致命。比如你在 description 里写“此技能用于提高代码质量帮助团队更好地协作”看似没问题但对调度器来说这句话几乎没有任何信息量——它没有说明什么场景该触发、什么场景不该触发、输入是什么格式、输出要满足什么标准。我自己总结过一个类比提示词模板就像你在咖啡店里口头告诉店员“我要一杯少糖的拿铁”而 SKILL.md 是这家咖啡店的完整 SOP包含原料配比、水温控制、出品标准、异常处理方案。服务员可以凭口头指令做一杯还行的拿铁但要让每一杯都稳定必须有 SOP。1.3 一个判断标准删掉你的 SKILL.mdAgent 的行为是否明显退化这是我一直推荐给团队的一个快速鉴别方法把你的技能文件暂时从技能目录中移除然后用同样的任务去问 Agent。如果它的输出和加载技能时几乎一样恭喜你——你的技能其实就是一段换了个格式的提示词模板它没有提供任何增量价值。真正的技能应该让 Agent 的行为产生明显变化要么输出结构更规范要么处理流程更完整要么在某些边界情况下学会了拒绝。如果删不删没差别说明 SKILL.md 里的内容没有超出模型参数里已有的知识那就不值得做成技能。这个判断标准在实战中特别有用。我见过不少团队一个技能目录里塞了几百个 SKILL.md结果调度器经常选错技能就因为大部分技能的描述和指令都写得含含糊糊。与其贪多不如先把核心两三个技能打磨到“删掉就会退化”的程度。2. SKILL.md 的物理结构与字段设计2.1 一个标准技能目录应该长什么样先说目录再说字段。技能不是一个单文件而是一个目录这是 SKILL.md 和提示词模板在物理形态上的第一层差异。目录的意义在于你可以给技能配上脚本、数据文件、长文档而不是把所有东西都塞进一个 Markdown 里。我比较常用的一个标准布局是这样my-skill/ ├── SKILL.md # 技能入口元信息 核心指令 边界 ├── scripts/ # 可执行脚本比如解析器、调用工具的逻辑 ├── assets/ # 静态资源比如模板文件、示例数据 ├── references/ # 参考资料长文本放这里按需加载 └── examples/ # 完整输入输出范例这个结构的关键思路是“入口要薄资源要厚”。SKILL.md 本身不要写得太长它的职责是让调度器看得懂、让模型拿得到主流程真正的大段参考资料、数据字典、模板代码全部放到子目录里等任务真正执行到那一步再读取引用。这样做的好处有两个第一调度器在判断是否触发技能时只需要读 description不需要把整个技能内容加载进上下文成本低、速度快第二模型在执行技能时可以按需查看 references 里的细节不会因为技能文档过长而丢失重点。2.2 frontmatter 元信息name 与 description 的写法SKILL.md 的顶部是一段 YAML frontmatter它相当于技能的“标签页”。最核心的字段就两个name 和 description但这两个字段的写法恰恰是大多数人最容易翻车的地方。name 要短要像一个功能名而不是一个角色名。比如code-review、meeting-minutes、>--- name: code-review description: 对代码 diff 或代码文件进行结构化评审输出问题清单、风险等级、修改建议。 当用户要求“评审代码”“review 一下”“看看这段代码有什么问题”或提交包含代码变更的 PR/MR 审查场景时触发。不适用于解释代码逻辑的请求也不适用于重写整个项目。 ---这个描述里有明确的触发动词“评审”“review”“看看有什么问题”有输入条件代码 diff 或代码文件有输出能力问题清单、风险等级、修改建议还有反例“不适用于解释代码逻辑”。调度器拿到这段描述匹配的准确率会高很多。2.3 正文部分是“可执行流程”不是“角色设定”frontmatter 下面是正文。很多从提示词模板改造过来的人会在这里写大段角色设定什么“你是全球顶级的代码评审专家拥有二十年经验”这些内容对技能执行没有实质性帮助。正文应该写的是执行该技能时的完整操作流程。我习惯把它组织成几个标准小节Instructions操作步骤、Examples范例、Boundaries边界声明。Instructions 会按时间顺序列出执行步骤并且每个步骤尽量包含可验证的标准Examples 提供至少一个完整的输入输出对Boundaries 明确什么情况不能做、什么情况必须停下来问人。你可以把正文想象成一份给新员工看的作业指导书它不强调“你是谁”而是强调“你按什么顺序做什么事、做到什么程度算完成、遇到特殊情况怎么办”。2.4 references 和 scripts把重物从主文档里挪出去最后是 references 和 scripts 这两个辅助目录。它们的作用是把“知识负担”和“计算负担”从模型身上卸下来。references 目录适合放长文档比如某个技术方案的完整背景、一份行业规范、一个数据字典。这些东西如果都写进 SKILL.md会把上下文撑爆放在 references 里让模型在执行到相关步骤时按文件名去读取效率高得多。scripts 目录则适合放真正可执行的代码比如把一段文本转成结构化 JSON 的脚本、调用内部 API 的封装。有了 scripts技能就不只是“动嘴”还能“动手”。3. 手写一份“代码评审”技能的完整拆解3.1 场景定义与 description 打磨空谈没用我直接拿一个实战例子来拆。假设你要给团队做一个“代码评审”技能目标场景是Agent 在收到代码 diff 或代码文件时输出结构化评审意见帮助开发者在 PR 合并前发现问题。第一步不是写正文而是先把 description 打磨好。我上面给过一版这里再补充一个细化过程。第一版你可能会写description: 对代码进行评审提高代码质量。这版的问题前面已经说过——没有触发场景调度器只能靠猜。你需要问自己三个问题用户说什么话最可能意味着需要一个代码评审技能这个技能接收什么样的输入文本 diff、GitHub PR URL、还是一个代码文件这个技能产出的东西和普通对话里的建议有什么区别想清楚之后description 会变成这样--- name: code-review description: 对代码 diff、代码片段或代码文件进行结构化评审输出按严重级别排序的问题清单 每条问题包含定位、原因、建议和代码示例。当用户请求 review 代码、要求“看看这段代码 有什么问题”、或提交 PR/MR 待审查时触发。不适用于解释代码用途、不适用于教学场景 也不适用于没有给出具体代码的任务。 ---这一版描述调度器已经能比较准确地决定“什么时候该用我”了。注意里面我特别加了“不适用于”的部分这些否定项在工程里极其重要能显著减少误触发。3.2 指令的分层结构维度、等级、输出格式接下来是正文的核心Instructions。这一段要写的是“当技能被触发后Agent 具体应该怎么做”。我的建议是采用分层结构不要写成一坨流水账。第一层是评审维度也就是告诉 Agent 从哪些角度检查代码。不要只写“检查代码质量”要拆开比如正确性逻辑是否有明显错误、边界条件是否被处理安全性是否存在注入风险、敏感信息泄漏、权限校验缺失可维护性命名是否清晰、函数是否过长、重复代码是否可抽象性能有无明显低效循环、N1 查询这类问题第二层是问题分级。评审结果的输出要给每个问题标等级我建议用三个级别P0必须修复包含明显的 bug、安全漏洞或会导致线上故障的问题P1应该修复影响可维护性或潜在性能瓶颈但不影响当前功能P2建议优化属于风格、命名、注释层面不影响上线第三层才是输出格式。我要求 Agent 输出时每个评审点都遵循固定的结构包含“位置定位—问题描述—严重级别—修改建议—示例代码”。这样做的好处是评审结果可以被下游工具直接解析也能让开发者在 PR 评论里快速定位问题。3.3 范例与反例的放置时机Examples 小节放在 Instructions 后面它的作用是给模型一个“标准答案”作参考。我强烈建议至少给一个正面范例和一个反例。正面范例是完整的输入输出对。比如给一小段有问题的 JavaScript 代码作为输入然后展示符合上述格式的评审输出。模型在看到输出格式的具体样子之后生成结果的稳定度会明显提升。反例同样重要。比如你可以放一个“反面例子”说明当用户只是问“这段代码是干什么的”时技能不应该被触发而应该直接把控制权交还给主对话。把“什么不该做”也写进范例里能显著减少技能被滥用的情况。3.4 边界声明什么情况下技能必须拒绝执行最后是 Boundaries。这些内容是提示词模板时代最容易被忽略的但在技能化之后边界声明决定了技能的安全底限。我给代码评审技能会写这样几条边界当提供的代码超过 2000 行时不直接评审而是建议分块提交或先让用户指定重点文件当代码不完整、无法运行或缺少关键上下文时不强行评审先要求补充信息当代码涉及机密信息时不输出完整代码片段只描述问题和修改方向这些边界本质上是在定义“技能在什么条件下可以工作、什么条件下必须说不知道、什么条件下要停下来问人”。边界写得越清楚技能在真实环境里的可靠度越高。4. 部署后不生效的四种典型故障与排查链路4.1 故障一调度器永远不触发这个技能这是最常遇到的情况——技能文件写得很好但 Agent 在一次任务里根本不去用它。排查链路我建议从两个方向走第一检查 description 是否和用户的真实表达存在语义距离。比如用户在对话里说的是“帮我瞅瞅这段代码有没有坑”而你 description 里的触发词写的是“当要求进行 structured code review 时触发”这两者之间的语义距离就太远了。解决办法是把 description 写得口语化一些多收集真实的触发表达。第二检查技能目录是否在 Agent 的可见目录列表里。很多框架支持配置哪些目录可以被调度器扫描如果你把技能放进了根目录但没配置递归扫描或者放进了例外列表那调度器根本看不到它。这是很蠢但真实存在的低级错误排查的时候先把目录路径和配置翻一遍。4.2 故障二触发了但 Agent 只读了技能的一个开头第二种情况更隐蔽技能确实被触发了但 Agent 的输出完全看不出它读了整份 SKILL.md只像是瞥了一眼 description 就开始自由发挥。这个问题的根因通常是 SKILL.md 正文太长或者关键步骤埋在大段段落中间模型在有限上下文里没抓取到。解决办法有两个方向一是把正文瘦身确保每个核心步骤都短促有力尽量用列表而不是长篇段落因为列表对模型来说更容易被解析。二是把“第一步”写得极其明确比如“第一步读取 references/checklist.md 并根据其中的 20 条检查项逐项评审”。一旦模型执行了第一步被强制去读参考资料后面的流程就顺了。4.3 故障三技能把上下文撑爆了上下文超限也是高频故障。症状表现为执行到一半报错或者技能文档里的关键内容被截断。原因无非是技能目录里的内容太重。有人习惯把一个团队的知识库全部塞进 references结果每次加载技能都要吞几万 Token。合理的做法是在 SKILL.md 里只保留最小可执行的流程references 只放当前任务真正可能用到的文件并且给每个 reference 配一个“何时读取”的说明。这样模型不会把所有文件都读进来只在需要时按需读取。还有一个小技巧如果某个参考资料只有特定分支场景才用到可以用 conditional 的方式在指令里声明“仅在用户提到原生应用时才读取 references/mobile-checklist.md”。这能把平均 Token 开销降下来一大截。4.4 故障四技能与 Agent 主指令打架最后一种典型故障是技能内容和 Agent 的系统提示词产生了冲突。比如系统提示词要求“所有输出用 JSON”但 SKILL.md 里的范例输出是 Markdown 表格模型两头为难最后输出一个四不像。排查的方式是先把 Agent 的系统提示词和 SKILL.md 里的指令放一起逐条对照重点看输出格式、处理原则、权限边界这三类信息是否矛盾。一旦发现冲突要么在 SKILL.md 开头显式声明“本技能输出优先遵循自身格式约定”要么反过来把系统提示词的要求写进技能里。没有谁绝对优先但必须明确一个规则不能两套标准同时存在。5. 技能不是一切理清与记忆、工具、工作流的边界5.1 记忆存事实技能存方法很多 Agent 项目把记忆系统做得很重然后又做了一个同样很重的技能库结果两者之间的边界模糊功能重叠严重。我的原则很简单记忆存事实技能存方法。比如“用户团队使用 Python 3.11 和 FastAPI”这种项目背景属于事实放在记忆里而“如何对 FastAPI 项目做 Code Review”这种流程属于方法放在技能里。如果反过来把事实写进技能技能就会变得非常不可复用——换个团队、换个项目技能就失效了把方法写进记忆每次对话都要占用上下文还很难被主动触发。5.2 调用工具时参数校验和异常处理放在技能层技能和工具的关系也需要理清。一个常见的困惑是技能内部该不该直接写死调用工具的参数我的经验是技能层应该负责生成参数、校验参数、处理异常而工具层只做一件事——执行并返回结果。比如代码评审技能里可能需要调用一个静态扫描工具技能负责把用户输入的代码转换成工具期望的参数格式如果参数缺失技能应该主动询问用户而不是直接把空参数抛给工具。异常处理也一样工具返回非零退出码时技能应该有一层兜底的解释逻辑而不是让 Agent 茫然地把原始错误输出转给用户。这种分层设计的好处是工具可以被多个技能复用而技能的编排逻辑不会渗进工具里。如果你发现某个技能里到处是不同工具的参数转换代码说明这个技能做得太宽了应该考虑拆成多个更小的技能。5.3 技能之间的编排要显式声明依赖当技能数量多起来之后技能之间会发生编排关系。比如“生成周报”可能需要先调用“汇总 Git 提交”技能再调用“数据分析”技能。这种依赖关系我建议在 SKILL.md 里显式声明而不是靠模型临场臆测。我常用的做法是在 Boundaries 或 Instructions 末尾加一段“相关技能”说明## Dependencies - 本技能假设 git-summary 技能已可用如果用户提供 Git 仓库路径先调用该技能获取提交记录。 - 如果用户没有提供仓库路径不要自行猜测直接询问。显式声明依赖能让模型在编排时有一个明确的秩序而不是每次任务都临时设计一套执行顺序。处理编排时也要注意防止循环依赖技能 A 依赖 BB 又依赖 A这种设计会让调度器死循环目录结构设计阶段就尽量避免。6. 验证技能质量的三个土办法6.1 换一个更笨的模型跑三遍技能写出来之后我建议不要拿你日常用的最强模型去验证而是换一个更弱、更笨的模型跑三遍。这个办法虽然土但非常有效。强模型在理解模糊指令时有很好的“脑补能力”即使你的 SKILL.md 写得稀烂它也可能做出不错的结果弱模型没有这个能力你指令里哪里有歧义、哪步缺条件它会直接暴露出来。如果在弱模型上都能稳定跑出符合预期的结果这个技能在强模型上的表现只会更好。反过来如果换到弱模型就歇菜说明技能里其实藏着大量不成文的隐性假设这些假设在真实业务场景里早晚是坑。跑三遍则是一个稳定性检验。如果三遍结果差异很大说明指令里存在模型自由发挥的空间太大你应该继续加约束——要么把输出格式定得更死要么把中间步骤说得更具体。6.2 用“最小可用版本”快速试错另一个建议是不要一上来就把技能做得大而全。先做一个最小可用版本只包含一个场景、三五个步骤、一个范例然后放到真实任务里跑。跑通了再加边界再补反例再增加 references。我在早期犯过的错误就是追求完美一个代码评审技能第一版就写了十多个评审维度、配了二十多个参考文件结果在真实任务里错误百出根本分不清哪些环节哪里坏了。后来拆成最小版本只保留正确性和安全性两个维度跑通之后再慢慢加可维护性和性能维度问题定位瞬间就变得清晰了。6.3 给每个技能建立变更日志最后一个是工程化层面的习惯给每个技能建立一个变更日志文件记录每次修改的原因和验证结果。这件事看起来不起眼但实际价值非常大。技能的迭代过程和普通代码一样必然经历反复调整。这周改了 description 的措辞下周调整了输出格式再隔两周又把输出格式改回去了——如果没有变更日志你根本不知道哪个版本对应哪种行为。而且技能文件通常是 Markdown很多团队不会把它纳入代码评审流程变更日志至少能帮你回溯“上一次改崩了是什么时候改的、改了什么”。我通常会在技能目录里放一个CHANGELOG.md格式很简单日期、修改人、修改内容、验证结论。一行一条不需要花哨但能救命。最后说一个我自己的个人习惯。每次写完一份 SKILL.md我不会直接丢给 Agent 跑任务而是先把它打印出来假装自己是一个完全不知道背景的新同事照着这份文档走一遍流程。如果每一步我都知道该做什么、做到什么程度算完成这份技能才算真正合格。这个习惯帮我过滤掉了大量“看起来专业、实际上全是废话”的技能描述。如果你现在维护的技能库里有不少文件从来没有被调度器正确触发过不妨按这个方法重新审视一遍把每一份 SKILL.md 都当成一份要给同事使用的操作手册来写效果会立竿见影。