从零掌握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.md

SKILL.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 技巧五：用“版本迭代”持续优化Skill

Skill不是写完就完了，需要在实践中持续迭代。我建议在SKILL.md里维护一个简短的变更记录：

## 变更记录 - v1.2.0：增加对LaTeX格式论文的支持 - v1.1.0：优化逻辑检查步骤，增加检查清单 - v1.0.0：初始版本

每次使用后，记录遇到的问题和优化点。比如发现AI总是漏掉图表检查，就在流程里加一步；发现输出格式不稳定，就加一个更严格的模板。

我个人的习惯是每周花15分钟回顾一下这周用Skill时遇到的问题，能改的当场改掉。积累下来，Skill的质量会越来越高。

提示：版本迭代不需要很正式，关键是养成“用完就优化”的习惯。一个用了半年的Skill，和刚写出来的版本，质量差距会非常大。

5. 实操全流程：从零写一个论文审阅Skill

5.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写得太短，只写了“审阅论文”，结果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，和刚写出来的版本，质量差距可能有三四倍。关键不是一次写多好，而是愿不愿意持续打磨。