从零掌握Skill编写：SKILL.md规范、目录设计与实战技巧

1. 从零理解Skill它到底是什么为什么值得认真写1.1 Skill不是插件也不是Agent很多人第一次接触Skill这个概念时会下意识把它和插件、Agent混为一谈。我刚开始也这样觉得不就是给AI加个能力嘛写个配置文件就完事了。但实际用下来才发现这三者的定位完全不同。Agent是一个能自主决策、调用工具、完成复杂任务的智能体它有自己的推理循环和行动策略。插件通常是给某个平台或框架扩展功能的代码模块偏工程侧。而Skill的本质是一份写给AI看的“操作手册”——它不执行代码不调用API只是用结构化的自然语言告诉AI遇到这类任务时你应该按什么步骤做、注意什么、输出什么格式。打个比方Agent是一个新入职的员工插件是给他配的电脑和软件而Skill就是岗位操作手册。手册写得好员工上手快、出错少手册写得烂员工要么瞎干要么频繁来问你。这个定位非常关键因为它决定了你写Skill时的核心思路——你不是在写代码你是在写一份让AI能准确理解并执行的文档。文档的质量直接决定AI的表现。1.2 为什么SKILL.md的规范如此重要SKILL.md是Skill的核心文件相当于整个Skill的入口和总纲。它的规范程度直接影响三件事第一AI能不能正确触发这个Skill。大多数支持Skill的平台会读取SKILL.md中的描述信息来判断当前任务是否匹配该Skill。如果你的描述写得含糊AI要么不触发要么乱触发。第二AI能不能按你预期的方式执行。SKILL.md里的步骤、约束、输出格式就是AI的行动指南。写得越清晰执行偏差越小。第三别人能不能复用和二次开发。一个规范的SKILL.md别人看一眼就知道这个Skill能干什么、怎么用、怎么改。不规范的只有作者自己能看懂。我见过太多人花大量时间调试Prompt却不愿意花半小时把SKILL.md的结构理清楚。结果就是每次用都要重新解释一遍需求效率极低。1.3 适合谁来读这篇内容如果你属于以下几类人这篇内容会对你有直接帮助已经在用各类AI工具想把自己的工作流沉淀成可复用Skill的人团队里需要统一AI使用规范想让不同人用AI产出质量一致的人对Agent Skills生态感兴趣想自己写Skill分享给别人用的人做科研、写论文、搞数学建模想把重复性工作交给AI的人不需要你有编程基础但需要你对“怎么让AI按规矩干活”这件事有实际需求。纯小白也能看懂因为我会把每个设计决策背后的原因讲清楚。2. 目录设计Skill的骨架怎么搭2.1 最小可用目录结构一个Skill的目录不需要很复杂但基本结构要清晰。我推荐的最小结构是这样的my-skill/ ├── SKILL.md # 核心文件必须存在 ├── references/ # 参考资料目录可选 │ ├── guide.md │ └── examples.md ├── scripts/ # 辅助脚本目录可选 │ └── helper.py └── assets/ # 静态资源目录可选 └── template.mdSKILL.md是唯一必须存在的文件。其他目录都是按需添加。我见过有人把所有内容都塞进SKILL.md结果文件几千行AI读起来效率很低自己也难维护。合理的做法是SKILL.md只放核心流程和索引详细内容放到references里需要时再引用。2.2 为什么目录名要用英文小写这个问题看似小但实际踩过坑。有些平台对文件路径大小写敏感有些对中文路径支持不好。用英文小写加连字符是最稳妥的方案。比如references不要写成References或参考文档。另外目录层级不要超过三层。层级太深AI在引用文件时容易搞错路径你自己维护起来也麻烦。如果内容确实多优先在文件名上做区分而不是加目录层级。2.3 references目录的组织逻辑references目录是放详细资料的地方。我一般按用途来分guide.md详细的操作指南或背景知识examples.md输入输出示例帮AI理解预期效果faq.md常见问题和边界情况处理changelog.md版本变更记录每个文件不要超过500行。超过就拆成多个文件在SKILL.md里用相对路径引用。比如详细的操作步骤请参考 [references/guide.md](references/guide.md)这样AI在需要时会去读取对应文件不需要时就不会加载节省上下文空间。2.4 scripts目录的使用场景scripts目录放的是辅助脚本。注意这些脚本不是Skill直接执行的而是给AI参考用的。比如你写了一个数据处理Skill可以把常用的数据清洗脚本放在这里SKILL.md里说明“如果需要清洗数据可以参考scripts/clean_data.py中的逻辑”。我个人的经验是scripts目录适合放那些逻辑固定、容易出错的代码片段。AI参考这些代码比纯文字描述更准确。但不要放太复杂的脚本否则AI理解成本太高。2.5 目录设计的三个常见错误第一个错误把所有内容堆在SKILL.md里。我见过一个SKILL.md写了3000多行AI每次加载都要消耗大量上下文实际执行时反而容易遗漏关键步骤。第二个错误目录结构太深。有人喜欢搞src/skills/core/utils/helpers/这种嵌套AI在引用时经常搞错路径。第三个错误文件名没有意义。比如file1.md、doc2.md这种过两天自己都不知道里面是什么。提示目录设计的原则是“扁平、清晰、按需拆分”。SKILL.md是总纲references是细节scripts是参考代码assets是模板资源。各司其职不要混在一起。3. SKILL.md规范每个字段都要有存在的理由3.1 头部元信息怎么写SKILL.md的开头通常需要一些元信息不同平台格式略有差异但核心字段差不多。我以最常见的YAML frontmatter为例--- name: paper-review-helper description: 帮助审阅学术论文检查逻辑漏洞、格式问题和引用规范 version: 1.2.0 author: your-name tags: [academic, review, paper] ---name是Skill的唯一标识用英文小写加连字符不要用中文或空格。description是最关键的字段它决定了AI什么时候触发这个Skill。写法上要包含“做什么”和“什么时候用”两个信息。我见过很多人把description写成“一个很有用的Skill”这种描述等于没写。好的描述应该是“当用户需要审阅学术论文、检查论文逻辑或格式时使用此Skill。适用于中英文论文支持LaTeX和Word格式。”version建议用语义化版本号方便追踪变更。tags用于分类检索不是必须但建议加上。3.2 触发条件的精确描述触发条件是SKILL.md里最容易被忽视的部分。很多人只写“这个Skill能做什么”不写“什么时候该用”。结果就是AI要么不触发要么在不该触发的时候触发。我的写法是在SKILL.md正文开头单独用一段说明触发条件## 何时使用此Skill 当满足以下条件时使用 - 用户提交了一篇学术论文需要审阅 - 用户询问论文的逻辑结构是否合理 - 用户需要检查论文的引用格式 以下情况不要使用 - 用户只是询问论文写作的一般建议 - 用户需要的是论文翻译服务这样AI在判断是否触发时就有明确依据。实测下来加上这段说明后误触发率能降低一半以上。3.3 核心流程的步骤化表达核心流程是SKILL.md的主体。写法上要步骤化、可执行、有顺序。我推荐用有序列表每个步骤包含三个要素做什么、怎么做、输出什么。比如一个论文审阅Skill的核心流程## 审阅流程 1. **通读全文提取核心论点** - 阅读摘要和结论确定论文的主要主张 - 输出用一句话概括论文的核心论点 2. **检查逻辑链条** - 逐段检查论证是否连贯是否存在逻辑跳跃 - 输出列出所有逻辑漏洞标注所在段落 3. **检查格式规范** - 对照目标期刊的格式要求检查引用、图表、公式 - 输出格式问题清单按严重程度排序每个步骤都要有明确的输出物这样AI执行时不会跑偏你验收时也有依据。3.4 输出格式的约束方法输出格式约束是保证AI产出稳定性的关键。不写清楚AI每次输出的结构都不一样你后续处理起来很麻烦。我一般用模板的方式约束输出## 输出格式 请按以下模板输出审阅结果 ### 核心论点 [一句话概括] ### 逻辑问题 | 位置 | 问题描述 | 严重程度 | |------|----------|----------| | 第3段 | 论据不足以支撑结论 | 高 | ### 格式问题 - [ ] 引用格式不一致第5页 - [ ] 图表编号缺失图3用表格和清单约束输出AI的产出会稳定很多。如果对格式要求特别严格可以在references里放一个完整的输出示例让AI照着模仿。3.5 边界情况与异常处理边界情况是区分Skill质量高低的重要维度。好的Skill会告诉AI遇到什么情况该停下来什么情况该问用户什么情况该跳过。比如## 边界情况处理 - 如果论文超过50页先询问用户是否需要分段审阅 - 如果论文是非中英文语言告知用户当前Skill不支持 - 如果论文缺少摘要跳过核心论点提取步骤直接进入逻辑检查 - 如果用户只提供了部分章节只审阅提供的部分不要推测缺失内容这些规则看起来琐碎但实际使用时能避免很多尴尬情况。我踩过的坑是没写边界处理AI对一篇法语论文硬生生用中文审阅了一遍输出全是胡编的。注意边界情况不需要一次写全可以在使用过程中逐步补充。每次遇到AI处理不当的情况就加一条规则进去。4. 五个编写技巧让Skill从能用变成好用4.1 技巧一用“角色设定”锚定AI的行为模式在SKILL.md开头给AI设定一个明确的角色能显著提升执行质量。这不是玄学而是因为角色设定会影响AI的语言风格、判断标准和关注重点。比如## 角色 你是一位有20年经验的学术期刊审稿人以严谨和挑剔著称。 你的审阅风格是先肯定论文的贡献再指出问题最后给出可操作的修改建议。 你特别关注论证逻辑和引用规范对格式问题零容忍。对比不写角色设定的版本实测下来写了角色设定的Skill在审阅深度和语言风格上都更稳定。AI会不自觉地模仿这个角色的行为模式。但要注意角色设定要具体不要写“你是一个 helpful assistant”这种废话。要写清楚经验年限、风格特点、关注重点。4.2 技巧二用“反面案例”划清边界正面示例告诉AI该怎么做反面案例告诉AI不该怎么做。两者结合效果最好。我在Skill里经常加一段“常见错误”## 常见错误不要这样做 - 不要只指出问题而不给修改建议 - 不要用“建议进一步研究”这种空话敷衍 - 不要把格式问题和逻辑问题混在一起说 - 不要在审阅结果里加入个人对论文主题的主观评价反面案例的作用是划清边界。AI在生成内容时会倾向于避免这些被明确禁止的行为。这比只写正面要求有效得多。4.3 技巧三用“检查清单”保证执行完整性检查清单是保证AI不遗漏步骤的利器。在SKILL.md末尾加一个检查清单让AI在输出前自查## 输出前检查清单 - [ ] 是否提取了核心论点 - [ ] 是否检查了所有段落的逻辑连贯性 - [ ] 是否对照了目标期刊的格式要求 - [ ] 是否给出了可操作的修改建议 - [ ] 输出格式是否符合模板这个技巧是我从代码审查流程里借鉴过来的。实测下来加了检查清单后AI遗漏步骤的概率大幅降低。因为AI在生成最终输出前会“过一遍”清单相当于一次自检。4.4 技巧四用“示例驱动”替代“规则堆砌”与其写一堆抽象规则不如给几个具体示例。AI从示例中学习的效果往往比从规则中学习更好。比如你要教AI怎么给论文写审阅意见与其写“审阅意见要具体、可操作、有建设性”不如直接给一个示例## 审阅意见示例 **不好的写法** “第3段的论证不够充分。” **好的写法** “第3段提出‘A导致B’的结论但仅引用了2019年的一项区域性研究 样本量仅120人不足以支撑普遍性结论。建议补充至少两项跨区域 研究或将该结论限定为‘在XX地区可能存在A导致B的现象’。”示例驱动的好处是AI能直接模仿不需要自己从规则推导。我一般会在references里放一个examples.md包含3-5个完整示例覆盖不同场景。4.5 技巧五用“版本迭代”持续优化SkillSkill不是写完就完了需要在实践中持续迭代。我建议在SKILL.md里维护一个简短的变更记录## 变更记录 - v1.2.0增加对LaTeX格式论文的支持 - v1.1.0优化逻辑检查步骤增加检查清单 - v1.0.0初始版本每次使用后记录遇到的问题和优化点。比如发现AI总是漏掉图表检查就在流程里加一步发现输出格式不稳定就加一个更严格的模板。我个人的习惯是每周花15分钟回顾一下这周用Skill时遇到的问题能改的当场改掉。积累下来Skill的质量会越来越高。提示版本迭代不需要很正式关键是养成“用完就优化”的习惯。一个用了半年的Skill和刚写出来的版本质量差距会非常大。5. 实操全流程从零写一个论文审阅Skill5.1 需求分析与场景定义假设我要写一个论文审阅Skill先明确需求目标用户需要审阅学术论文的研究生和科研人员核心功能检查逻辑漏洞、格式问题、引用规范输入论文全文中英文LaTeX或Word输出结构化的审阅报告使用场景论文投稿前自查、导师审阅学生论文、同行评审辅助需求明确后目录结构就清晰了paper-review-skill/ ├── SKILL.md ├── references/ │ ├── guide.md # 详细审阅指南 │ ├── examples.md # 审阅意见示例 │ └── format-check.md # 格式检查清单 └── assets/ └── report-template.md # 审阅报告模板5.2 SKILL.md的完整编写过程第一步写头部元信息--- name: paper-review-helper description: 当用户需要审阅学术论文、检查逻辑漏洞或格式规范时使用此Skill。支持中英文论文适用于投稿前自查和同行评审辅助。 version: 1.0.0 tags: [academic, review, paper] ---第二步写角色设定和触发条件## 角色 你是一位有20年经验的学术期刊审稿人以严谨和挑剔著称。 你的审阅风格是先肯定论文贡献再指出问题最后给出可操作的修改建议。 ## 何时使用 当用户提交论文全文或部分章节并明确要求审阅时使用。 当用户询问论文逻辑或格式问题时使用。 以下情况不要使用 - 用户只是询问写作建议 - 用户需要翻译服务 - 用户提交的是非学术类文档第三步写核心流程## 审阅流程 1. **提取核心论点** - 阅读摘要和结论 - 输出一句话概括论文核心论点 2. **检查逻辑链条** - 逐段检查论证连贯性 - 输出逻辑问题清单标注位置和严重程度 3. **检查格式规范** - 对照目标期刊格式要求 - 输出格式问题清单 4. **生成审阅报告** - 按模板组织输出 - 输出完整审阅报告第四步写输出格式和边界处理## 输出格式 请参考 [assets/report-template.md](assets/report-template.md) 中的模板。 ## 边界情况 - 论文超过50页询问用户是否分段审阅 - 非中英文论文告知不支持 - 缺少摘要跳过论点提取直接进入逻辑检查 - 只提供部分章节只审阅提供部分第五步写检查清单## 输出前检查清单 - [ ] 是否提取了核心论点 - [ ] 是否检查了所有段落的逻辑连贯性 - [ ] 是否对照了格式要求 - [ ] 是否给出了可操作的修改建议 - [ ] 输出格式是否符合模板5.3 references和assets的填充references/guide.md放详细的审阅指南比如逻辑检查的具体方法、常见逻辑谬误列表、引用规范检查要点。控制在500行以内。references/examples.md放3-5个完整的审阅意见示例覆盖不同学科和不同严重程度的问题。references/format-check.md放格式检查清单按期刊类型分类。assets/report-template.md放审阅报告的完整模板包括标题、摘要、逻辑问题表格、格式问题清单、修改建议等部分。5.4 测试与调优的实操记录写完后需要实际测试。我一般用三篇论文测试一篇自己写的、一篇有已知问题的、一篇格式规范的。第一轮测试发现AI对LaTeX格式的论文处理不好经常把公式和正文混在一起。解决方案是在SKILL.md里加一条“如果论文是LaTeX格式先提取正文文本忽略公式环境。”第二轮测试发现AI给出的修改建议太笼统比如“建议加强论证”。解决方案是在examples.md里增加更多具体示例并在SKILL.md里明确要求“每条建议必须包含具体位置和可操作的修改方向”。第三轮测试发现输出格式不稳定有时用表格有时用列表。解决方案是在report-template.md里固定格式并在SKILL.md里强调“严格按模板输出”。经过三轮调优Skill的稳定性明显提升。后续每次使用遇到问题就继续迭代。注意测试时要用真实场景的论文不要用自己编的简单示例。真实论文的复杂度和边界情况远超想象。6. 常见问题与排查技巧实录6.1 Skill不触发或误触发怎么办这是最常见的问题。排查思路如下现象可能原因解决方案完全不触发description太模糊重写description包含具体场景关键词偶尔触发触发条件不明确在SKILL.md里单独写“何时使用”段落频繁误触发触发条件太宽泛增加“以下情况不要使用”的排除条件与其他Skill冲突功能范围重叠明确各自边界或在description里区分我踩过的坑是description写得太短只写了“审阅论文”结果AI在用户只是问“论文怎么写”的时候也触发了。后来改成“当用户提交论文全文并要求审阅时使用”误触发就少了很多。6.2 输出格式不稳定的排查方法输出格式不稳定通常有三个原因第一模板不够具体。如果模板里只写“输出审阅结果”AI每次的结构都会不一样。要写清楚每个部分的标题、顺序、格式。第二约束不够强。在SKILL.md里要用“必须”“严格”“不要”这类强约束词。比如“必须按以下模板输出不要添加额外章节”。第三示例不够多。在examples.md里放2-3个完整输出示例AI会倾向于模仿示例的格式。我的经验是模板强约束示例三管齐下格式稳定性能达到90%以上。6.3 AI执行步骤遗漏的解决思路步骤遗漏通常是因为流程描述不够清晰或者步骤太多AI记不住。解决方案把流程控制在7步以内超过就合并或拆分到子流程每个步骤用加粗标题让AI容易识别在末尾加检查清单让AI输出前自查在关键步骤后加“不要跳过此步骤”的强调我试过把流程从12步压缩到6步遗漏率从30%降到了5%以下。步骤不是越多越好关键是每一步都要有明确的输出物。6.4 Skill在不同平台表现不一致的处理不同平台对Skill的支持程度不同表现不一致很正常。处理思路核心逻辑写在SKILL.md里平台特定配置放在单独文件用最通用的Markdown格式避免平台特有语法在description里注明支持的平台如果某平台表现特别差考虑为该平台单独写一个简化版我一般会维护一个platform-notes.md记录各平台的差异和适配方法。这样换平台时不用重新踩坑。6.5 独家避坑技巧汇总最后分享几个我踩坑后总结的技巧第一SKILL.md不要超过500行。超过就拆分到references里。AI的上下文有限太长的文件反而影响执行质量。第二用“必须”“不要”“严格”这类强约束词。AI对这类词的敏感度比“建议”“可以”高得多。第三每次修改后都要重新测试。有时候改了一个小地方会影响其他步骤的表现。第四保留历史版本。有时候新版本不如旧版本能回滚很重要。第五不要追求一次写完美。Skill是迭代出来的先用起来再慢慢优化。提示如果你写的Skill要给团队用建议在SKILL.md里加一个“使用说明”段落告诉使用者这个Skill适合什么场景、有什么限制、怎么反馈问题。7. 进阶方向让Skill更智能、更通用7.1 多Skill协作的设计思路单个Skill的能力有限多个Skill协作能完成更复杂的任务。比如论文审阅Skill可以和文献检索Skill、数据分析Skill配合使用。设计多Skill协作时关键是定义好接口。每个Skill的输入输出要标准化这样Skill之间才能无缝衔接。我一般会在SKILL.md里注明“本Skill的输出格式为XX可直接作为YY Skill的输入”。7.2 动态加载references的技巧references目录不需要一次性全部加载。可以在SKILL.md里用条件引用如果论文是LaTeX格式请参考 [references/latex-guide.md](references/latex-guide.md) 如果论文是Word格式请参考 [references/word-guide.md](references/word-guide.md)这样AI只在需要时加载对应文件节省上下文空间提升执行效率。7.3 从个人Skill到团队Skill的演进个人用的Skill和团队用的Skill要求不一样。团队Skill需要更详细的文档让不同人都能看懂更严格的输出格式保证产出一致性更完善的边界处理覆盖更多场景版本管理和变更记录方便追踪我建议个人Skill先用起来跑通后再考虑团队化。团队化时重点补充文档和边界处理。7.4 Skill的分享与复用策略如果你想把Skill分享给别人建议在SKILL.md里写清楚适用场景和限制提供完整的使用示例注明依赖的平台或工具保留变更记录方便别人了解迭代过程如果可能提供一个最小可用版本降低使用门槛我分享过几个Skill给同事反馈最好的是那些文档清晰、示例完整的。功能再强别人不会用也白搭。7.5 持续迭代的实用建议最后分享我个人的迭代习惯每周花15分钟回顾这周用Skill时遇到的问题能改的当场改。每月做一次大版本更新整理变更记录。每季度做一次全面测试确保核心功能稳定。不要等到Skill完全不能用了才去修。小步快跑持续优化才是长久之道。我在实际使用中发现一个持续迭代了半年的Skill和刚写出来的版本质量差距可能有三四倍。关键不是一次写多好而是愿不愿意持续打磨。