从零编写AI Skills：打造可复用专业能力包的实操指南

我第一次正经写 Skills，是被逼的。当时我折腾一个自动化场景，需要在不同会话里反复让模型做同一套流程：读取一段项目描述，按固定结构输出风险分析、进度评估、下一步建议。用普通提示词也做得到，但问题是每一次都得重新把规则粘贴一遍，稍微改一个词，输出格式就飘了。后来接触了 Skills，才意识到这东西本质上就是把“一次性提示词”升级成“可复用的专业能力包”，一旦加载，模型就成了那个领域里按流程办事的熟练工。

这篇内容不是官方文档的翻译，是我自己从零开始写 Skills、测试、踩坑、迭代之后沉淀下来的实操经验。我会把 Skills 到底是什么、动手前怎么设计、SKILL.md 的每个部分怎么写、怎么调试、以及最常见的几个坑全部拆开讲清楚。想系统学习 Skills 编写、或者正在为提示词不够稳定而烦恼的朋友，这篇应该能直接帮到你。

1. 先搞清楚Skills到底是什么：从“提示词升级”到“专业能力包”

1.1 它和普通提示词的区别，一句话就能说清

普通提示词是“一次性指令”，你这次对话告诉模型怎么做事，下次换一个会话就得重新说一遍。Skills 则是一个可复用的小型任务单元，本质上是把你对某个任务的完整要求——目标、步骤、规则、输出格式、注意事项——全部打包进一个结构化的文档里。模型学会调用它之后，只要你给出符合描述的输入，它就能按你预设的流程跑完整个任务。

我习惯把它类比成“岗位 SOP”。普通提示词是领导随口交代一句“你把这个报告处理一下”，能做成什么样全看临场发挥；Skills 是把“处理报告”的完整流程写成标准化手册——第一步看什么、第二步算什么、第三步怎么汇总、输出用什么模板，全部写死。模型拿到手上，就像新员工拿到一份图文并茂的操作手册，照着做就行。

很多人以为 Skills 是为了让模型“更聪明”，这个理解不太准确。Skills 解决的核心问题是稳定性和复用性：同样一批数据，不管你在早上还是晚上调用，不管换了多少次会话，输出结构都能保持一致。它把这个领域的专业流程固化下来了，这才是它最大的价值。

1.2 解决的核心问题：稳定性与复用性

稳定性这件事，用过的都知道有多痛。同一句话，今天问和明天问，答案可能相差十万八千里。尤其当你需要模型做“多步骤任务”时，普通对话模式下它经常走到第二步就把第一步的要求忘了，或者自己加戏，输出一些你根本不需要的内容。

Skills 的机制决定了它天然对抗这种“遗忘”。因为流程、规则、输出模板都写死在技能文件里，模型每一步执行时都可以回看原文，不容易跑偏。我自己实测下来的感觉是，加载了良好编写的 Skills 之后，输出的格式一致性提升非常明显，基本能做到“同样的输入，出来的是同一套骨架，只是内容在变化”。

复用性则体现在两个层面。一个是跨会话复用——不需要每次粘提示词了；另一个是跨场景复用——当你发现某个流程适合多个任务时，可以直接复制技能文件，改一改描述和规则就能适配新场景。比如我写过一个“结构化周报生成器”，后来改成“项目复盘报告生成器”，只花了十分钟，改的只是变量名和输出模块。这套思路一旦建立起来，后面所有同类需求都会变得非常轻。

1.3 哪些场景值得写Skills，哪些场景别硬写

不是所有任务都适合写成 Skills。我总结了一个简单的判断标准：任务是否同时满足“固定流程”“固定输出格式”“会重复使用”这三个条件。如果三个都满足，写成 Skills 会大大提升效率；如果三个里缺了两个，硬写反而会变成负担。

适合写的典型场景：

• 内容模板类：周报、月报、项目复盘、会议纪要，这类任务结构清晰，输出格式固定。
• 分析处理类：把一段原始数据或文本，按固定维度进行分析、归类、摘要，比如竞品信息提炼、用户反馈分类。
• 格式转换类：口语化记录转成规范文档，散碎要点扩写成完整文章，这种任务规则明确、批量使用频率很高。

不适合写的场景：

• 头脑风暴类：需要开放性发散、快速碰撞创意的任务，过度约束只会让输出变得死板。
• 信息完全未知的探索类：比如让模型帮你研究一个全新的领域，流程和结论都无法预定义，这时候更应该给自由对话的空间。
• 一次性的小任务：顺手就能做完的事情，不值得花半小时去写一个技能文件。

我见过很多人刚学会 Skills 就恨不得把每件事都封装成技能包，最后维护成本比手动操作还高。正确的心态是：Skills 是你的工具箱里的一个标准化工具，不是万能遥控器。用得上的地方才上，用不上的地方别强行套。

2. 动手前先想清楚：定义边界与目标比写正文更重要

2.1 第一步：用一句话描述这个技能的价值

很多人一上来就打开编辑器写 SKILL.md，这是最容易踩的坑。写技能的难点不在“怎么写”，而在“写之前你有没有想清楚这个技能到底解决什么问题”。想清楚的办法很简单：逼自己用一句话把它说出来。

比如“把凌乱的例会录音转成可执行的会议纪要”，这就是一句合格的价值描述。它说清楚了输入是“凌乱的例会录音”，输出是“可执行的会议纪要”，隐含了转化过程包含结构化整理、任务提取。而“写会议纪要”这种描述信息量就不够，别人看完也不知道你的技能和普通提示词有什么区别。

我给自己定了一个规矩：先用一句话写下价值描述，然后问自己三个问题——输入是什么？输出是什么？过程中最关键的处理动作是什么？如果这三个问题能在一分钟内回答出来，再开始动笔。如果答不出来，说明你还没理解这个任务，写出来的技能大概率是混乱的。

2.2 拆解任务流程：从输入到输出的转化链

下一步是把任务拆成“输入 → 加工 → 输出”这条转化链。这一步看起来简单，但它决定了整个技能的可执行性。

举个例子，假设你要做一个“竞品分析简报生成”的技能。输入可能是一段网页正文或用户粘贴的竞品信息；加工过程可能包含：先提取竞品名称、产品定位、核心功能、定价策略，再对比这些信息和你自有产品，最后给出差异化结论；输出则是按固定模板生成的简报。

我会把这个转化链拆成一张表：

这个拆解过程有两个关键作用。一是让你发现隐藏的缺失信息，比如“自有产品介绍”这个输入，如果你不提前列出来，运行到第二步时模型就会瞎编一个对比对象。二是在逐步拆解的过程中，你会看到哪些步骤是可以标准化的，哪些步骤必须依赖用户输入，边界自然而然地浮出水面。

2.3 圈定边界：明确告诉模型“不做什么”

边界是很多人容易忽略的部分。我最初写技能时只写“要做什么”，结果模型经常“超范围发挥”：让它整理会议纪要，它顺手编了一条并不存在的决策；让它做竞品分析，它把没有依据的猜测写进了结论。后来我才意识到，必须在技能文件里专门写一块“边界与禁止事项”，列出负面清单。

边界至少包括三层：

• 事实边界：没有依据的信息不得补充，信息缺失时标注“原文未提及”，而不是用推测补全。
• 职责边界：哪些判断由人来做，模型不做。比如“风险评估只负责罗列风险点，不负责给出最终决策建议”。
• 输出边界：什么情况下直接按模板输出，什么情况下应该先向用户提问澄清、向用户说明不满足输出条件。

写边界的时候，我的经验是“宁可多写一条，不要少写一条”。因为模型的默认行为就是“尽力回答”，你不告诉它边界在哪里，它就会按照“尽力回答”的惯性去做，然后你就会看到一个自作主张的输出结果。

这里还有一个容易被忽略的细节：边界条款写得越多，越需要与其他部分保持逻辑一致。比如你在“执行步骤”里让模型输出“下一步建议”，又在“边界”里写“不负责建议”，这就是自己冲突了。写完整个文件之后，通读一遍，检查规则之间有没有互相打架的情况，非常有必要。

3. 一份合格SKILL.md的核心结构：逐段拆解

3.1 YAML头部：name和description要怎么填

一个 SKILL.md 文件，最开头是 YAML 格式的头部信息，至少要包含 name 和 description 两个字段。这两个字段看着简单，其实直接影响技能能不能被正确调用。name 建议全小写、用短横线连接，比如 meeting-minutes、weekly-report，方便识别，也方便未来在工具链中引用。description 则要写清楚“什么时候该使用这个技能”，它决定了模型在什么场景下会主动唤起这个技能包。

description 的写法有一个常见的误区：写“这个技能可以用来写周报”。这句话描述的是技能本身的功能，但对模型来说不够实用。更好的写法是描述触发场景：“当用户需要将一阶段的工作内容整理成结构化周报时使用，输入为零散的工作记录或要点，输出为按模块组织的周报。” 两者的区别在于，前者只说了“能干什么”，后者还包含了“什么输入情况下触发”和“会产出什么形式的结果”，模型看到这样的描述，才能在你提到相关需求时准确调用它。

我自己的习惯是，写完 description 之后，再往后面加一句变量说明式的简短描述，比如“用户需提供项目名称与工作周期”，这样模型在触发前就知道这个技能需要哪些信息，它会主动向用户询问缺失项，而不会拿到一个残缺的输入就开始硬跑。

3.2 正文主体：目标、步骤、规则、输出四段式

正文是技能文件的核心，我的组织方式是把内容分成四段：目标、执行步骤、规则约束、输出模板。这个顺序不是随便排的，它的逻辑是：先让模型理解“最终要完成什么”，再告诉它“具体怎么走”，然后告诉它“走的时候要注意什么”，最后告诉它“走完怎么呈现结果”。

目标段落要简短，两三句话就够。比如“本技能用于将用户提供的零散实验记录整理为结构化的实验报告。报告需包含实验目的、方法、结果与结论四部分，结果部分必须保留原始数据，不得自行加工。” 这一段不需要展开细节，它的作用是让模型对任务形成整体认知。

执行步骤是整个文件最关键的部分，要按编号顺序写清楚每一步动作。我一般会写成：

1. 提取用户输入中的实验目的、方法描述、原始数据。
2. 核对原始数据的完整性。
3. 将数据按时间序列重新排序。
4. 生成结果描述，在描述中保留所有数值数据。
5. 输出结构化报告。

规则约束部分放“必须”和“禁止”的条款，比如“必须保留数据的原始单位”“禁止在结果部分补全缺失数值”“遇到明显异常数据时，在报告中单独标注，不要直接修改”。输出模板部分则给出最终产物的结构骨架，甚至可以给出空模板。

这四个模块写完之后，整个技能的基本盘就稳了。后续所有调试和迭代，都是在为这四个模块做细化调整。

3.3 变量：用模板符号标记输入位

一个可以复用的技能，必然存在动态输入的部分。同一个周报技能，这周和上周的原始记录不同；同一个竞品分析技能，不同竞品的资料不同。这些动态的内容，需要用变量来标记。

变量的标准写法通常是用花括号包裹，比如 {项目名称}、{工作周期}、{原始记录}。在技能文件里，我第一次提到这些内容时，会顺带说明它的来源和处理方式。比如：“将用户提供的原始记录{原始记录}按时间排序”，这样模型就知道这里要接收的是一段待处理的文本，而不是一个固定值。

变量设计有一个很重要的原则：宁缺毋滥。变量的数量越多，模型处理时的困惑越强。如果某个信息在大多数情况下可以通过上下文推测出来，那就不必设计成变量。比如“当前日期”这种信息，模型基本能从环境里拿到，就不需要额外要求用户输入了。真正需要设计成变量的，只有那些“内容随每次使用变化的、影响核心处理逻辑的信息”。

我在调试中还发现一个现象：明确的变量名比模糊的变量名更容易让模型正确填充。比如 {用户原始笔记} 就比 {内容} 好，因为它能提示模型这里应该填入用户给的那段笔记，而不是模型自己生成的内容。

3.4 示例与资源引用：给模型“抄作业”的锚点

一份纯规则堆叠的 SKILL.md，就像一份没有案例的手术指南，医生（模型）知道步骤，但很难感受到每一步落在纸面上应该长什么样。所以我强烈建议每一个技能文件里都保留至少一组“输入 → 输出”示例。

示例的作用不是学习知识，而是校准格式。模型的模仿能力非常强，你给它一组标准的输入输出对照，它在处理类似输入时，输出的结构和语气就会自动向示例靠拢。这是我在多次调试中验证过的，效果非常明显。

示例的具体布局，常见的是单独设置一个 Examples 小节，每个示例内部先写“用户输入”，再写“预期输出”。预期输出最好直接给出成品结构，不要只描述“应该有标题和结论”。不过注意，示例的数量要克制，一到三组足够。示例太多，模型会把示例里的具体内容当成模板来抄，反而容易造成格式僵化。一个好的示例，应当明确标注“示例中的具体数据仅用于展示格式”，避免模型把示例中的内容当成真实数据写进实际输出。

对于一些复杂技能，比如需要调用外部工具或参考长文档的，还可以把辅助说明拆到单独的文件里，比如 references 目录或 examples 目录；在 SKILL.md 里用相对路径引用它们。这样主文档保持清爽，技能包整体又能承载足够多的细节。

4. 编写指令正文的高质量技巧：说清楚、给约束、给示例、给检测

4.1 用编号步骤替代大段描述

写 SKILL.md 的时候，有一个常见误区：试图用一大段文字把所有要求描述清楚。比如“你需要对用户提供的文本进行细心的分析，分析过程中要重点关注各种可能忽略的细节，然后基于分析结果输出一份结构清晰、格式规范的报告。” 这句话看起来没什么问题，但模型对它的遵循效果很差。因为它没有给出可执行的指令锚点，更像是一句模糊的期望描述。

我的建议是，把这种模糊期望改写成明确的编号步骤。举一个我实际改写的例子：

改前：“对用户提供的会议记录进行内容整理，发现其中的行动项。”
改后：

1. 阅读用户提供的会议记录全文。
2. 将内容按议题分组。
3. 从每个议题的讨论内容中提取结论。
4. 根据结论找出行动项，标明责任人和截止日期。
5. 按模板输出整理后的纪要。

两相对比，第二种写法每一步都是一个明确的动作，模型的执行路径非常清晰。如果你在实践中发现某个技能输出不稳定，先回头检查一下执行步骤是不是存在“一段式描述”的情况，把它拆成编号步骤，往往会有立竿见影的改善。

4.2 让模型在“追问”和“假设”之间做出正确选择

动态任务中最难处理的情况是“输入不完整”。用户可能只给了项目背景，没给目标；可能给了一份数据表，没解释表头字段含义。面对这种缺失，模型的默认行为是“用自己的常识补全”，这就很容易产生幻觉。

我后来在技能里加了一条规则，明确告诉模型在什么情况下应该追问，什么情况下可以自行假设。我的写法是：“执行第一步前，检查输入是否包含{必需输入}中列出的全部字段。若缺失关键字段，先向用户提问补齐，最多追问三次；三次仍无法补全时，在输出开头明确标注‘以下输出基于对缺失字段的假设’，再继续执行。”

这条规则的价值在于，它把“是否要追问”这个模糊问题变成了一个程序化的判断。模型不需要自己权衡什么时候该问、什么时候不该问，只需要照着条件检查就行。如果缺少的是非关键字段，根本不影响核心输出，就不用反复打断用户；如果缺少的是关键字段，就必须追问，宁可多问一句也比输出错误结果好。

4.3 加一个自检清单，让输出更可控

自检机制是我后期才养成的习惯，但它对输出质量的提升非常显著。具体做法是，在技能文件的最后增加一个小节，要求模型在正式输出完成后，按清单逐项自查一遍：

• 是否覆盖了用户要求的全部模块？
• 所有关键数据是否保留原始数值与单位？
• 是否有事实性描述缺少依据？
• 输出格式是否与模板一致？
• 是否存在自我推测但未标注的内容？

可能有人担心，让模型自检会增加多余的输出，显得累赘。其实不用把这个过程展示给用户，而是让模型在内部完成自查，只输出最终的成品。但对模型来说，有了这个“输出后检查”的环节，它在生成阶段就会更谨慎，因为它知道自己要面对这些检查项，提前就会避免错误。

4.4 用语气和人称规则控制最终呈现效果

输出风格的控制，往往比控制内容更让人头疼。同样是周报，发给自己看的和发给领导看的，语气人称完全不一样；同样是分析报告，给技术团队看的和给业务团队看的，措辞方向也不一样。这些信息都需要在技能文件里显式声明。

比如我写过一个给业务团队看的分析类技能，其中就有这样一条规则：“输出中所有分析结论使用清晰、非技术性的语言；避免专业缩写，如需使用首次出现时给出中文解释；对外输出统一使用‘我们’，不对用户使用‘您’的敬语称呼。” 有了这条规则之后，输出风格立马变得统一了，不再随机出现各种奇怪的语气。

如果你需要技能输出供直接发布的内容，还可以在规则中指定“输出内容需经过一次内部润色，去除口语化表达和多余的语气词”。这类风格约束虽然看起来像是小事，但在反复使用的时候，它就是决定输出是否能直接使用的那最后一道工序。

5. 从“能跑”到“好用”：测试、调试与迭代

5.1 三种必测输入：正常、边界、混乱

写完一个技能包，先不要急着投入使用。我习惯用三组不同的输入来测试，分别对应正常情况、边界情况和混乱情况。

正常输入就是符合你预期的标准用例。比如你做会议纪要技能，就给它一段结构完整、议题清晰的会议记录，看输出的格式对不对、内容全不全。边界输入则是考验极限的用例。比如超长输入（一两万字的会议记录）、超短输入（只有一句话“开会讨论了项目进度”）、缺少关键字段的输入（没有参会人员名单）。你的技能在边界情况下表现怎么样，决定了它会不会在关键时刻掉链子。混乱输入则是故意给它一段错别字多、逻辑跳跃、夹杂无关内容的文本，看技能能不能保持稳定，或者至少给出“输入质量过低”的提示而不是硬着头皮瞎分析。

我每测完一组，都会记录下输出结果和问题。这个测试记录，就是下一轮迭代的起点。

5.2 常见失效模式与修改方向

测完之后，你大概率会看到技能“翻车”。翻车不可怕，关键是要能定位到原因。我把自己遇到的常见问题整理成了一张表：

5.3 版本管理：给Skills建一个小版本表

技能文件是不折不扣的代码，只是它运行在模型上而已。所以也应该像代码一样管理版本。最开始我完全没做版本管理，改了一版觉得不行，想回退的时候发现已经找不到原来那版了，只能凭记忆重写，非常痛苦。

现在我的习惯是，在技能的目录下保留一个 git 仓库，每一次修改都在提交说明里写清楚“改了什么”“为什么要改”“测试结果怎么样”。没用过 git 的朋友也用不着紧张，哪怕只是按日期保存一个副本文件，也比没有强。核心逻辑是，你在迭代过程中一定会出现改回去的情况，留好历史版本，省下的时间远超记录的时间。

我的推荐做法是给每个技能维护一个简短的 Changelog 文件，内容只需要包含日期、版本号、变更说明三列。不需要写得很长，每行一句话就够。

6. 避坑清单：我从失败案例中学到的经验

6.1 技能文件不是小作文，规则越简洁越有效

我写废掉的第一个技能，规则写了将近两千字，涵盖了所有我能想到的边界情况。结果那个技能每次运行效果都稀碎，因为规则太多，模型根本分不清哪些是核心流程、哪些是约束条件，最后为了不违规，输出变得瞻前顾后，完全没有重点。后来我删掉了三分之二的废话，只保留核心步骤、关键边界和输出模板，效果反而好了。

这个教训给我的启发是：每条规则都要有明确的“可检验性”。如果一条规则无法判断模型有没有遵守，那它大概率会被忽略或曲解。写完后通读一遍，看到模棱两可的表述就删掉或改写，让每一条规则都落到具体动作上。

6.2 示例里的具体内容，模型真的会照着抄

我早期做一个数据报告技能的时候，在示例里写了一个真实感很强的数据“43.7%”，结果后续所有实际数据进来，那个位置都顽固地输出43.7%。最后排查了半天才发现是示例造成的，示例数据被模型当成了默认输出格式的一部分。这个问题非常隐蔽，一旦发生会持续影响以后每一次调用。

修正方法有两个。第一，示例中的动态数据统一用占位符，比如 {{比例值}}、{{项目名称}}；第二，在示例开头明确标注“以下示例中的数据仅为演示格式，与实际输入无关”。两种方法我都用过，双管齐下最保险。

6.3 输出格式约束过度，反而会破坏输出质量

最开始我总想把输出的格式用 Markdown 语法约束得非常细致，甚至规定了每一级标题用什么字号、表格列宽是多少。结果模型经常为了符合格式而牺牲内容的自然流畅，句子变得机械而僵硬。后来我放宽了纯视觉层面的格式要求，只规定内容层面的结构（比如必须有结论段、必须有数据依据段），具体渲染交给它自己决定，输出的自然度立刻恢复了。

记住一个原则：格式约束应当服务于内容的可读性，而不是反过来。硬编码的格式越少，模型理解任务的负担越小，输出与其内容本身的匹配度反而越高。

6.4 警惕“万能技能”的诱惑

最后一个坑很典型。总有一种冲动，想写一个能处理所有写作任务、分析任务、总结任务的“超级技能”。但实际经验是，技能越通用，运行效果越差。因为它要在内部处理无数种分支逻辑，对模型的理解能力要求太高。

后来我改成“一技能一事”的做法：一个技能只服务一个明确的任务场景。把一个大流程拆成几个小技能，在使用时按需分别唤起。别担心技能文件太多会管理不过来，一个命名规范清晰的文件目录，远胜过一个内部逻辑复杂到连你都看不懂的超级技能。我自己的目录结构就是一个场景一个文件夹，文件夹里放 SKILL.md 和相关的参考资料，长期维护下来非常清爽。

补充一个我自己的习惯：写完一版技能之后，一定用三到五组真实数据跑一遍，然后把对话记录保存下来，放到这个技能的“测试记录”里。过了几周如果发现改动出了问题，我还能回到这些记录里对比。这个过程不能省，它带来的回报是后续所有调优都不用从头再来，也是我现在写技能越来越快的原因。