先讲个我常碰到的情况很多人一听说“skill”第一反应就是“哦不就是把一段很长的 prompt 整理一下吗”然后照着网上的模板填一填塞进 agent 的工具目录跑通一个例子就算完事了。结果真到换场景或者换数据源的时候要么完全不动要么改一处崩三处最后只能放弃回头继续手写 prompt。我这两年折腾 skill 相关的事情最大的体会是skill 不是一个 prompt 文件而是一次“能力建模”。它能不能跨场景复用、能不能被 agent 稳定地调用、能不能在团队里交给别人维护靠的不是灵光一现的措辞而是一套可重复的方法。这篇文章想分享的就是我从大量实践里抽象出来的一套创建流程。核心是五个阶段锁定需求场景、抽象能力模型、实现最小可用版本、验证并打磨边界、复盘归档外加一份 Review 清单用来给 skill 的质量兜底。不管你在用的是 Claude Code、Codex还是其他支持自定义技能包的 agent 工具这套方法的思路都是通用的。适合三类人看一是写过几个 skill 但总觉得不好用的人二是准备在团队里把 skill 工程化、规范化的人三是对 agent 自动化感兴趣、想少走弯路的开发者。1. Skill 到底在解决什么问题1.1 Skill、Prompt、Workflow 和 Agent 的关系很多人把 skill 和 prompt 混为一谈这是很多问题的根源。我用一个比较生活化的类比来解释。Prompt 就像你随口跟一个新来的实习生说“帮我把这份会议记录整理一下”。实习生可能听懂了也可能没听懂整理出来的格式全看他的发挥。Workflow 是你给实习生画了一条固定流程第一步做什么第二步做什么判断条件是什么做完以后递给你什么。Agent 是那个实习生本人——他能自己看情况调用各种工具、拆解任务、逐步执行。Skill 是什么呢Skill 不是“一句话指令”而是一种可以反复调用的能力包。它通常包含一个说明文档、若干示例、必要的模板或者参考文件。你交给 agent 的不仅仅是一句话而是一整套“操作手册 模板 工具包”。下次再遇到同类任务agent 可以直接把整个能力包拿出来用而不是临时理解你的一句话。用表格看会更清楚名词本质类比复用性Prompt一次性指令随口交代低Skill可复用的能力封装操作手册 模板 工具箱高Workflow固定步骤的流程编排SOP 流程图中Agent自主执行任务的载体能看情况办事的实习生最高结论是如果你的任务只做一次写 prompt 完全够用但如果你发现自己每隔几天就要用类似的方式处理类似的事那就该把它 skill 化了。1.2 大多数 skill 写出来不好用的原因我在实际看过不少别人写的 skill也 review 过团队里提交上来的 skill发现一些高度重复的问题。第一类是为了写而写。有些人看到别人发了 skill自己也照着格式写一个但根本没想清楚这个 skill 要在什么场景下、给谁用、解决什么痛点。结果就是“这也能叫 skill”一点存在感都没有。第二类是贪多求全。一个 skill 想覆盖十几种场景文档写了几千字示例五花八门agent 加载以后光读说明书就要消耗大量上下文执行起来反而犹豫不决、频繁跑偏。第三类是缺少边界处理。只在理想场景下测试过稍微遇到一点格式异常、输入缺失就崩了。比如让模型提取日期结果用户给的是“上周五”而你的 skill 只认“YYYY-MM-DD”它就直接报错或者乱提取。第四类是可维护性太差。所有说明、示例、参数塞在一个超大文件里后来要改一个小逻辑简直是牵一发而动全身最后只能推到重写。这些问题不是靠“多写几次”能解决的而是需要一个稳定的流程来约束。这也是我为什么要写这篇方法论把从需求到复盘的全过程固定下来。2. 高效创建 skill 的五步流程2.1 第一步锁定需求场景而不是直接想 prompt很多人写 skill 的第一个动作是打开编辑器开始敲字这是错的。正确顺序是先回答几个问题把场景锁死。这个 skill 要在什么场景下被使用是每周一次的例行整理还是偶尔出现的批量处理谁来用是只给自己用还是团队成员都会用他们使用的时候会不会补充额外说明输入的原始材料长什么样是会议录音转写文本、聊天记录导出还是代码仓库里的 Markdown 文件期望的输出物是什么格式、长度、颗粒度有没有硬性要求如果输入不符合预期希望 skill 怎么做是报错、跳过还是自动修复后继续这一步产出物是一段“场景描述”。举个例子不要写“帮我整理会议纪要”而要写“我每周五下午会导出一周以来的会议转写稿每篇大约 2000 到 5000 字语言是中文夹杂英文术语。我需要你提取每场会议的目标、决策、待办事项、风险点并生成一份按会议分节、按议题归并的周报总字数不超过 800 字待办需要标出负责人和截止时间”。看到没有锁定了场景以后后面的抽象和实现才有依据。没有这个基础写出来的 skill 就是无根之萍。2.2 第二步抽象能力模型把需求变成接口场景锁定之后不要急着写文案先做抽象。抽象的目标是把“一个一个的具体任务”归纳成“一类能力”。我常用一个三步法列变体把所有可能遇到的任务变体都列出来。同样一个“会议纪要整理”可能会有“周会、项目评审会、1对1 沟通”等不同场景输出要求也可能完全不同。找公共骨架这些变体里哪些是不变的流程几乎都会有“读取原始文本 → 理解讨论脉络 → 提取要点 → 按固定结构输出”这几步。参数化差异点变体现在不同的地方比如输出语言、是否需要生成待办、标题格式等把它们变成可配置的参数而不是各自写死。抽象完以后你会得到一个“能力模型”它包含四个要素输入接口、输出接口、处理步骤、可配置参数。此时你还没有写任何具体的 prompt但已经知道这个 skill 长什么样子了。这里有个判断标准如果你发现这个 skill 的输入输出接口跟另一个已有的 skill 高度重合那就需要考虑是不是该合并或者拆分成“获取输入 → 处理 → 输出”的子能力。抽象的目的不是把东西变复杂而是让每次新增场景时的“增量成本”尽量小。2.3 第三步实现最小可用版本重点是结构抽象完成后才开始动笔写实现。一个典型的 skill 目录结构通常是这样的my-skill/ ├── SKILL.md # 主说明文件含 frontmatter 和核心指令 ├── examples/ # 示例输入和输出方便 agent 理解 │ ├── example-input.md │ └── example-output.md ├── references/ # 参考资料、详细规则、模板 │ ├── template.md │ └── rules.md ├── scripts/ # 可选的辅助脚本 │ └── preprocess.py └── assets/ # 可选的静态资源这里的核心是 SKILL.md。它不应该是一篇说明文而应当是面向模型的结构化指令。我习惯把 frontmatter 里写好 name 和 descriptiondescription 尤其关键因为 agent 依靠它来判断“什么时候该用这个 skill”。description 写得太宽泛agent 容易在无关场景调用写得太狭窄该用的时候又找不到。--- name: meeting-minutes description: 将会议转写稿或聊天记录整理为结构化纪要。适用于周会、评审会、1对1沟通等场景。输入为原始转写文本输出为含会议目标、决策、待办、风险的结构化文档。 ---正文部分建议用“角色 背景 步骤 输出格式”的结构但别写太长。一个常见的误区是以为写越多模型执行得越准实际上超过模型上下文舒适区以后多余的说明反而会稀释注意力。把长内容放进 references在 SKILL.md 里只保留索引和关键决策点是我强烈建议的做法。“最小可用版本”的意思就是先别追求完美先把主流程跑通。从 0 到 1 的阶段你只需要覆盖 60% 的“黄金场景”剩下的边界可以后面再补。2.4 第四步验证并打磨边界别急着宣布成功我第一次写 skill 的时候跑通了一个例子就觉得自己完成了结果换个场景立刻翻车。后来我总结了三层验证法。第一层是黄金场景验证直接把最容易出现的那个场景拿来做测试看输出是否符合预期。比如会议纪要这个例子就拿一份真实的周会转写稿来试而不是用自己虚构的素材。第二层是变体验证针对你抽象时识别的“参数化差异点”逐个改变参数再测试。比如把语言改成英文、把输出格式从 Markdown 改成表格、把输入长度增加三倍看模型是否还扛得住。第三层是对抗验证故意给那些可能让 skill 崩溃的输入比如空文本、全符号文本、输入内容里没有会议信息等。你要确认的是它不会“硬编造”一份纪要出来而是会报错、要求补充信息或者输出一个明确的“无有效内容”的占位结构。这一步产出的是一张测试记录表。哪条过了、哪条没过、改动以后影响什么全部记下来。这张表后面会直接变成你 Review 清单的素材。2.5 第五步复盘、命名与归档很多人的 skill 写完就开始用用完了也不复盘导致同类问题在下一次写新 skill 时再次踩坑。我建议每次完成一个 skill 以后抽出 10 分钟做一个轻量复盘。复盘要回答三个问题抽象出的能力模型是否真的覆盖了实际使用场景验证阶段暴露的问题有没有共性能不能沉淀成一条“编写规范”这个 skill 的命名和描述是否足够让人或让 agent一眼看懂它该何时使用命名这里有个小建议用“动词 对象”的格式比如generate-report、extract-contacts、summarize-changelog尽量避免用utils、helper、misc这种含糊的名字。归档的时候把还在迭代中的版本放到工作目录把稳定版本放到正式的 skills 目录把废弃版本直接移走或是打上 deprecated 标记不要留在原地干扰 agent 的判断。3. 方法抽象是核心中的核心3.1 抽象不是想当然而是找到“可跨场景复用的那一层”做 skill 设计的时候“抽象”这个词是最容易误导人的。有些人一上来就想要一个“万能 skill”什么都能处理结果什么都处理不好。这里要分清抽象层级。我把抽象分成三层操作级抽象处理某个具体的原子操作比如“把 Markdown 表格转成 CSV”“提取一篇文章的关键词”。任务级抽象完成某个完整的任务比如“把会议转写稿整理成结构化纪要”。它内部会组合多个操作。角色级抽象模拟某种身份或专业角色比如“资深产品经理”“数据分析师”。这类 skill 通常不绑定具体任务而是提供思维方式。选择哪个层级取决于复用场景。如果你只需要在多个任务中复用“把表格转 CSV”这一步那操作级就够了如果你每周都有“整理会议纪要”的完整任务那就应该落到任务级只有当你想给 agent 建立一种长期稳定的“行为方式”时才需要考虑角色级。大多数失败的 skill 都是因为层级没选对。把角色级当操作级用会显得空泛把操作级当任务级用又扛不住复杂输入。3.2 参数化把“差异”变成“变量”而不是派生效副本这是方法抽象里最重要的一步。我在实际项目里见过一种反面典型因为要支持“中文会议”和“英文会议”有人直接复制了整份 skill改了几个词变成两个文件。这样当然也能用但一旦要修改公共逻辑就得同步改两份改到后面必然出现不一致。正确做法是把差异点参数化。我拿“会议纪要整理”继续举例变化维度一次性做法参数化做法语言写死“中文”language: zh/en输出格式只输出 Markdownformat: markdown/table/json待办要求不生成待办include_todos: true/false摘要长度固定 200 字max_summary_words: 200/500/800发言人标注不需要with_speaker: true/false参数不是越多越好。我见过一个日志分析 skill 列了二十多个参数结果 agent 在执行的时候光理解参数就花掉了大量上下文。我个人的经验是保留那些真正会改变处理逻辑的参数把那些只是微调表述的参数砍掉。如果两个参数导致的结果差异只有 5%大概率不值得暴露给用户。参数化之后使用 skill 的方式就变成了在调用时传入参数而不是为每种场景维护一个副本。这也是“方法抽象”最直观的收益。3.3 警惕两种抽象失败过度抽象与过浅抽象抽象这件事失败案例往往比成功案例更有教育意义。过度抽象的典型表现是为了让 skill“更通用”把步骤写得模棱两可比如“根据材料类型选择合适的处理方式”。这句话表面上看是灵活实际等于没写模型根本不知道该怎么选。每次调用结果都像开盲盒。过浅抽象的典型表现是只抽取了一个参数其他所有内容都是复制粘贴改词。这种 skill 本质上还是“一堆 prompt 副本”没有解决复用问题。我给自己定了一个检验标准当一个新的同类场景出现时改动能不能控制在“一个文件、一个参数、一个段落”以内如果不能说明抽象层级选错了或者抽象得不够。还可以用一个公式来衡量抽象的收益复用收益 复用次数 × 每次节省的时间。只有当收益明显大于抽象成本时才值得把某个能力从一次性需求里“抽”出来。有些任务一年就用两次抽象它纯属自我感动。4. Review 清单把质量底线固定下来4.1 为什么靠感觉靠不住必须用清单人有两种典型的判断偏差第一自己写的东西怎么看都顺眼第二能跑通一次就默认“没问题”。这两种偏差放到写 skill 上会直接导致质量失控。评审清单的作用不是限制创造力而是把基础的质量底线固定下来。就像写代码要有 code review 一样写 skill 也应该有 review。对于个人开发者这份清单能在发布前帮自己“泼一盆冷水”对于团队协作这份清单则可以作为合并到主分支之前的门禁。我把清单分成两层门禁级和加分项。门禁级不满足就绝对不能合并加分项可以根据实际情况取舍。4.2 主清单从结构到体验的九个检查项我整理了九个检查域基本覆盖了我 review 过的 skill 里会反复出现的问题。检查域检查项通过标准常见失败案例结构完整性目录和文件是否齐全SKILL.md、examples、references 齐备引用路径正确示例文件路径写错agent 找不到接口明确性输入输出是否有清晰描述描述可被 agent 检索到且不依赖用户额外解释description 写得太泛导致无关场景误调用示例有效性示例是否覆盖主流程至少有一个完整输入输出对能引导模型理解任务示例与真实任务差异过大模型照猫画虎反而出错边界处理非法输入是否有兜底遇到格式异常能报错或输出占位结构不硬编造输入为空时模型生成了虚构的会议纪要上下文预算主文件是否控制篇幅SKILL.md 在 1000 字以内长内容放 references文档超过 4000 字模型加载后频繁偏离主任务安全与权限是否避免高危操作不诱导模型执行系统级命令脚本有权限校验skill 让模型直接删除目录酿成事故可维护性是否便于后续迭代参数集中定义公共逻辑无重复两个参数作用重叠改动互相影响可发现性名称和描述是否准确命名符合“动词对象”描述能匹配触发场景名叫utilsagent 根本不会主动调用最终体验是否值得被反复使用输出结果稳定模型没有频繁犹豫或返工同一个输入反复跑每次结果差异巨大这九个检查项不需要每次全部做到完美但至少门禁级结构完整、接口明确、边界处理、上下文预算、安全必须过关。4.3 10 分钟快速 review 法如果觉得完整清单太重可以用一个轻量版本的快速 review。它只需要三个问题一个完全没接触过这个 skill 的 agent拿到文件后能不能不追问就完成主流程如果可以说明结构清晰、示例有效如果需要猜测说明描述和示例还没到位。当输入不符合预期时skill 是会优雅降级还是直接崩溃优雅降级包括报错、输出占位结构、要求补充信息直接崩溃包括编造结果、无限循环、执行危险命令。我要新增一个同类场景时改动量是多少如果超过一个小节就说明抽象层级或者参数化做得不够。这三个问题分别对应着可读性、鲁棒性和可扩展性。每次发布新 skill 之前花 10 分钟过一遍这三个问题能过滤掉绝大多数低级问题。4.4 一份可以直接复制的 Review 清单模板下面的模板可以直接粘贴到你的项目仓库里作为 skill 合并前的必检项。## Skill Review Checklist - [ ] SKILL.md 存在于根目录frontmatter 包含 name 和 description - [ ] description 能在目标场景下被 agent 正确触发 - [ ] 输入接口和输出格式有明确、具体的说明 - [ ] 至少有一个完整的主流程示例输入 正确输出 - [ ] 对空值、格式异常等边界输入有兜底行为 - [ ] SKILL.md 主体不超过 1000 字长内容放 references - [ ] 不包含任何危险操作或未授权的副作用 - [ ] 参数集中定义不同参数之间没有职责重叠 - [ ] 命名遵循“动词 对象”无歧义 - [ ] 经过至少一个真实场景的测试且测试结果已记录5. 一次真实案例复盘一个“客户反馈周报” skill 的诞生5.1 需求背景看似简单其实暗藏很多坑有一段时间我每周都要把散落在各种群聊、邮件、文档里的客户反馈整理成周报。任务是找出客户提了哪些问题、哪些需求按产品和优先级分类再生成一份给团队看的周报。一开始我完全不觉得这需要写 skill直接让 agent 读我粘贴的内容就行。第一周效果还不错第二周换了新的聊天记录它把我同事之间互相吐槽“这个功能真是难用”也当成了客户反馈整理出来的周报失真的离谱。我意识到问题不在于“让 agent 理解自然语言”而在于“如何定义客户反馈”。5.2 重新进入五步流程从场景锁定到参数化我重新走了一遍流程。第一步锁定场景后我明确了这个 skill 的输入不是我随手粘贴的文本而是“客户在公开渠道或售后渠道产生的内容不包括内部同事讨论”。同时输出必须有“反馈原文摘录、对应产品模块、问题/需求分类、优先级”四个部分。第二步抽象能力模型时我发现真正核心的能力其实是“从非结构化聊天文本里识别出哪些内容属于‘外部用户反馈’剔除掉内部讨论和无关闲聊”。这一步属于任务级抽象可以复用到别的场景比如舆情监控、竞品分析。第三步实现时我把“反馈识别规则”写进了 references/rules.md在 SKILL.md 里只放主流程和调用路径。所有关于“什么是客户反馈”的详细判据放在规则文件里后续想调整判断标准不必动主文件。5.3 踩过的三个坑坑一开始没管输入范围导致 agent 把研发群的技术讨论误判成客户反馈。解决方式是加了一个前置步骤先标记“消息来源”再根据来源决定是否进入反馈分析流程。坑二参数塞太多。我在第一版里加了include_sentiment、include_version、include_channel、include_priority等一堆参数结果模型光理解参数就消耗了大量上下文整理出来的周报反而丢了三项重要信息。后来砍到只剩format和max_items两个参数效果立刻稳定下来。坑三示例太长。最初我在 examples 里放了一份接近 3000 字的完整聊天记录想“展示真实场景”结果 agent 处理新输入时总是往示例的格式和内容上“靠”而不是按规则处理。后来我把示例压缩到只有两段对话同时附上标准的输出结构问题就消失了。5.4 最终版本的输出效果最终的 skill 在测试里对一份包含 120 条消息的聊天记录能正确识别出其中 18 条客户反馈准确率和召回率都比我预期的要好而且输出稳定同一个输入跑三次结果基本一致。这件事之后我更加确信好的 skill 不是一次写出来的而是在验证和复盘里磨出来的。6. 常见问题速查表6.1 一张表解决 80% 的排查我自己写 skill 过程中遇到过的典型问题整理成了一张速查表可以按图索骥。现象可能原因排查方向agent 在无关场景调用了 skilldescription 太宽泛触发条件不明确收紧 description增加“仅当…时使用”该用的时候 agent 却不用描述与触发场景不匹配或命名太难理解用具体场景词重写 description测试不同措辞执行结果忽好忽坏不稳定示例不足或示例与真实输入差异过大增加高质量示例压缩规则文本输出格式经常跑偏输出格式说明不具体示例缺失提供明确模板和反例模型加载 skill 后上下文不够用SKILL.md 太长或 references 被整体加载压缩主文件长内容拆分为按需读取修改一个参数后别的环节崩了参数职责重叠或文档前后不一致集中定义参数检查文档是否同步更新遇到空输入或异常输入时编造结果缺少边界处理指令加入“如果输入无有效信息则输出占位结构”等兜底规则skill 在团队里没人用缺乏可发现性或名字太含糊改名、补充 description、写一份简短使用说明6.2 三个容易忽略但很要命的细节第一frontmatter 里的 description 不是给人看的是给模型检索用的。很多人把 description 写成给同事看的简介结果 agent 判断是否调用时抓不住关键信息。建议包含触发场景、输入类型、输出类型三个要素并且用“仅当”“当……时”这类约束词。第二格式问题不只是美观问题。YAML frontmatter 的缩进、SKILL.md 里的标题层级、列表符号都会影响模型解析。同一个 skill 在一种模型上表现良好换一个模型可能就因为解析差异完全失效。发布前至少在每个目标模型上跑一次主流程。第三skill 的“品味”需要有意积累。很多 skill 功能上没问题但用起来就是“不对劲”这大多出在对示例、措辞、细节的品味上。我的建议是遇到一个你觉得“这个 skill 真聪明”的实现不要只是收藏拆开看看它的示例怎么选的、规则怎么排布的、参数怎么命名的。看得多了写出来的 skill 自然会有质感。最后分享一个我自己一直在用的小技巧我会在工作目录里保留一个名字叫scratch的草稿 skill任何新想法先丢进去随便写、随便改等它跑通了、稳定了再走一遍正式流程把它收拾干净。这样做的好处是不会因为“还没想好”就干脆不写也不会让半成品污染正式目录。写 skill 和写代码一样最难得的不是“会写”而是“有一套稳定的流程让自己每次都写得可靠”。希望这份流程和清单能帮你少走一些我走过的弯路。