从Prompt到Skill：可复用AI能力包的工程化实践指南

1. 从零理解 Skill：它到底是什么，为什么值得折腾

第一次接触 Skill 这个概念，很多人会把它和 Prompt 混为一谈。我刚开始也是这么想的——不就是一段提示词嘛，写长一点、写细一点不就完了？但真正用起来才发现，Skill 和 Prompt 的关系，更像是“菜谱”和“今天想吃什么”的关系。Prompt 是你当下对模型说的一句话，Skill 是你提前封装好的一套可复用能力包，里面可能包含多个 Prompt、若干 MD 文件、脚本、配置，甚至依赖关系。

我最初是在做一套自动化文档处理流程时被迫研究 Skill 的。当时的需求很朴素：每周要处理几十份结构类似的 Markdown 文件，做格式校验、字段提取、模板替换。如果每次都手写 Prompt，不仅累，而且每次输出格式还不稳定。后来我把这套流程拆成了一个 Skill，用 MD 文件定义规则，用 Prompt 做触发，用脚本做后处理，整个效率直接翻了几倍。从那以后我就意识到，Skill 不是“更长的 Prompt”，而是一种工程化的能力组织方式。

Skill 的核心价值在于三点。第一是可复用，你写一次，后面所有同类任务都能调用，不用重复造轮子。第二是可组合，一个 Skill 可以调用另一个 Skill，像搭积木一样拼出复杂流程。第三是可维护，规则写在 MD 文件里，改起来比改一坨 Prompt 清晰得多。尤其是当团队协作时，Skill 让“某个人会用的技巧”变成了“所有人都能调用的资产”。

那 Skill 适合谁？如果你只是偶尔问模型几个问题，那确实用不上。但如果你有重复性的任务、有固定的输出格式要求、有多个步骤需要串联，或者你想把某套方法论沉淀下来反复使用，那 Skill 就非常值得投入时间。我见过做科研的朋友用 Skill 管理文献检索和摘要生成，也见过做运营的同事用 Skill 批量处理文案模板，甚至有人用 Skill 来做数学建模的标准化流程。场景不同，但底层逻辑是一样的：把“每次都要想一遍”变成“一次定义，多次执行”。

这里还要提一个容易混淆的概念：Skill 和 Agent 的区别。简单说，Agent 是一个能自主决策、调用工具、多轮交互的执行体，而 Skill 是 Agent 可以调用的一个能力单元。你可以把 Agent 理解成一个员工，Skill 理解成这个员工掌握的一项技能。员工可以有很多技能，也可以在执行任务时选择用哪个技能。所以学 Skill 不是替代学 Agent，而是为 Agent 准备弹药。

2. Skill 的文件结构与 MD 文件的核心作用

2.1 为什么 MD 文件是 Skill 的骨架

Skill 的载体通常是一组文件，而 Markdown 文件在其中扮演了“规则说明书”的角色。为什么是 MD 而不是 JSON 或 YAML？我的理解是，MD 文件对人类友好，对模型也友好。人类读起来是文档，模型读起来是结构化指令，两边都不用做额外的转换。而且 MD 文件天然支持标题层级、列表、代码块、表格，这些恰好是描述 Skill 规则时最常用的表达形式。

一个典型的 Skill 目录结构大概长这样：

my-skill/ ├── SKILL.md # 主定义文件，描述技能名称、触发条件、输入输出 ├── rules/ │ ├── format.md # 格式规则 │ └── validate.md # 校验规则 ├── prompts/ │ ├── extract.md # 提取用 Prompt │ └── rewrite.md # 改写用 Prompt ├── scripts/ │ └── post_process.py └── examples/ ├── input.md └── output.md

这个结构不是强制的，但我在实践中发现，把“规则”“提示词”“脚本”“示例”分开存放，后期维护成本最低。尤其是当 Skill 变复杂时，所有东西堆在一个文件里会让人崩溃。

2.2 SKILL.md 里到底该写什么

SKILL.md 是入口文件，它的内容决定了模型怎么理解这个 Skill。我一般会包含以下几个部分：

• 技能名称与描述：一句话说清楚这个 Skill 是干什么的，越具体越好。比如“从学术论文 PDF 中提取方法章节并生成结构化摘要”就比“处理论文”好得多。
• 触发条件：什么情况下应该调用这个 Skill。可以是关键词触发，也可以是任务类型触发。
• 输入要求：需要用户提供什么，格式是什么，有没有必填项。
• 输出格式：输出应该长什么样，最好附一个示例。
• 执行步骤：分步骤描述处理流程，每一步做什么、用什么工具、注意什么。
• 依赖与限制：需要哪些外部工具，有什么已知限制。

我踩过的一个坑是：一开始把 SKILL.md 写得太抽象，结果模型每次执行都靠“猜”，输出极不稳定。后来我把每个步骤都写成“动词+对象+约束”的形式，比如“读取输入文件，按二级标题切分，保留标题下的所有段落，不修改原文”，稳定性立刻上来了。所以我的经验是：SKILL.md 不是写给人看的说明书，而是写给模型看的操作手册，能具体就绝不含糊。

2.3 MD 文件的编辑工具选择

热词里有人问“md文件用什么软件打开”“如何利用 vx code 编辑 md 文件”，这确实是实操中绕不开的问题。我自己的工具链是这样的：

• VS Code：主力编辑器，装 Markdown All in One 插件，支持预览、目录生成、快捷键格式化。编辑 SKILL.md 时我习惯左边写右边预览，改完直接保存。
• Typora：写纯文档时用，所见即所得，适合写规则说明和示例文件。
• Obsidian：管理多个 Skill 之间的关联时用，双链功能方便追踪依赖关系。
• 命令行工具：批量处理 MD 文件时用pandoc做格式转换，用markdownlint做格式校验。

提示：编辑 SKILL.md 时一定要开启“显示空白字符”，因为 MD 对缩进和空行敏感，一个多余的空格可能导致列表层级错乱，模型解析时就会出错。

3. 创建 Skill 的完整实操流程

3.1 需求拆解：先想清楚再动手

创建 Skill 的第一步不是写文件，而是拆需求。我一般会问自己四个问题：

1. 这个任务重复出现的频率有多高？如果一周用不到一次，可能不值得做成 Skill。
2. 任务的输入输出是否稳定？如果每次输入格式都不一样，Skill 的规则就很难写。
3. 任务是否可以拆成明确的步骤？步骤越清晰，Skill 越好写。
4. 有没有现成的 Skill 可以复用或改造？别重复造轮子。

举个例子，我之前做过一个“论文摘要生成”的 Skill。需求是：输入一篇论文的 MD 文件，输出包含研究问题、方法、结论、局限性的结构化摘要。拆解后发现，这个任务可以分成四步：读取文件、识别章节、提取关键信息、按模板输出。每一步都可以单独定义规则，最后串起来就是一个完整的 Skill。

3.2 编写 SKILL.md 的具体步骤

假设我们要创建一个名为paper-summary的 Skill，下面是我实际编写 SKILL.md 的过程。

第一步，定义技能元信息：

# Skill: paper-summary ## 描述 从学术论文 Markdown 文件中提取核心信息，生成结构化摘要。 ## 触发条件 当用户提供论文 MD 文件并要求生成摘要时调用。 ## 输入 - 论文 MD 文件路径（必填） - 摘要模板类型（可选，默认 standard） ## 输出 结构化摘要，包含以下字段： - 研究问题 - 方法 - 主要结论 - 局限性

第二步，写执行步骤：

## 执行步骤 1. 读取输入文件，确认文件存在且为 MD 格式。 2. 按二级标题切分文档，识别以下章节： - Introduction / 引言 - Method / 方法 - Results / 结果 - Discussion / 讨论 - Conclusion / 结论 3. 对每个识别到的章节，调用 extract prompt 提取关键句。 4. 将提取结果按输出模板组装。 5. 检查输出是否包含所有必填字段，缺失则标注“未找到”。

第三步，附上示例：

## 示例 ### 输入 （论文 MD 文件片段） ### 输出 - 研究问题：本文旨在解决... - 方法：采用...方法，通过...实验验证 - 主要结论：实验表明... - 局限性：样本量较小，未考虑...

这个 SKILL.md 写完后，我实际测试了十几篇论文，发现两个问题：一是有些论文的章节标题不标准，比如用“Methodology”而不是“Method”；二是有时候提取的关键句太长，摘要不够精炼。于是我在规则里加了同义词映射表，并限制了每段提取的句子数量。改完之后，输出质量明显提升。

3.3 Prompt 在 Skill 中的嵌入方式

Prompt 是 Skill 的“执行引擎”。在 SKILL.md 里，我通常不会把完整的 Prompt 写进去，而是引用单独的 Prompt 文件。这样做的好处是 Prompt 可以独立迭代，不影响 Skill 的整体结构。

比如prompts/extract.md的内容可能是：

# Extract Prompt 你是一个学术论文信息提取助手。请从以下文本中提取关键信息： 要求： - 只提取与指定字段相关的内容 - 每段提取不超过 3 句话 - 保持原文术语，不要改写 - 如果找不到相关信息，输出“未找到” 文本： {{input_text}} 字段：{{field_name}}

然后在 SKILL.md 里用{{prompts/extract.md}}这样的占位符引用。实际执行时，系统会把 Prompt 文件和输入文本组装起来发给模型。

这里有个细节值得注意：Prompt 里的变量占位符格式要统一，我一般用双花括号{{variable}}，因为这种格式在大多数模板引擎里都支持，不容易和 MD 语法冲突。

3.4 脚本与后处理

有些任务光靠 Prompt 搞不定，比如格式校验、文件重命名、数据统计。这时候就需要脚本介入。我一般用 Python 写后处理脚本，放在scripts/目录下。

比如一个校验输出格式的脚本：

import re import sys def validate_summary(text): required_fields = ["研究问题", "方法", "主要结论", "局限性"] missing = [] for field in required_fields: if field not in text: missing.append(field) if missing: print(f"缺失字段: {', '.join(missing)}") return False return True if __name__ == "__main__": content = sys.stdin.read() if validate_summary(content): print("校验通过") else: sys.exit(1)

这个脚本可以在 Skill 执行完 Prompt 后自动运行，确保输出符合要求。我通常会把脚本的调用也写进 SKILL.md 的执行步骤里，形成完整闭环。

4. 修改与迭代 Skill 的实战经验

4.1 什么时候该改 Skill

Skill 不是写完就一劳永逸的。我一般在这几种情况下会回去改：

• 输出不稳定：同样的输入，有时候输出好有时候输出差。这通常是规则不够具体，或者 Prompt 有歧义。
• 新场景出现：原来只处理中文论文，现在要处理英文论文，需要加规则。
• 效率瓶颈：某个步骤太慢或太耗资源，需要优化。
• 依赖变化：外部工具升级或接口变了，Skill 要跟着改。

我印象最深的一次修改，是一个文档处理 Skill 在处理超长文件时总是截断。排查后发现是 Prompt 里没有限制输入长度，模型自动截断了。后来我在 SKILL.md 里加了“如果输入超过 8000 字，先分段处理再合并”的规则，问题就解决了。

4.2 修改 Skill 的正确姿势

改 Skill 最忌讳的是直接在生产环境改。我的做法是：

1. 复制一份到dev/目录，在副本上改。
2. 准备一组测试用例，覆盖正常情况和边界情况。
3. 对比修改前后的输出，确认改进有效且没有引入新问题。
4. 记录修改原因和效果，写在CHANGELOG.md里。
5. 确认无误后再合并回主目录。

这套流程看起来麻烦，但能避免“改了一个地方，崩了三个地方”的惨剧。尤其是当多个 Skill 之间有依赖关系时，改一个可能影响一片，必须谨慎。

4.3 版本管理与协作

如果是一个人用，用 Git 管理 Skill 目录就够了。如果是团队协作，我建议每个 Skill 独立一个仓库，或者至少独立一个目录，配上清晰的 README。

版本号我一般用语义化版本：主版本.次版本.修订号。规则大改升主版本，加功能升次版本，修 bug 升修订号。这样别人引用你的 Skill 时，能清楚知道升级会不会破坏兼容性。

注意：Skill 的修改要同步更新 SKILL.md 里的描述和示例，否则文档和实际行为不一致，后面用的人会被坑。

5. 常见问题与排查技巧实录

5.1 Skill 不触发或触发错误

这是最常见的问题。表现是：明明写了触发条件，但模型就是不调用，或者在不该调用的时候调用了。

排查思路：

• 检查触发条件是否太宽泛或太狭窄。太宽泛会导致误触发，太狭窄会导致不触发。
• 检查 SKILL.md 的元信息是否完整。有些平台要求必须有name、description、trigger字段。
• 检查是否有同名 Skill 冲突。如果有两个 Skill 名字很像，模型可能选错。

我的经验是：触发条件里最好包含具体的任务类型关键词，而不是泛泛的“处理文档”。比如“当用户要求从论文中提取方法章节时”就比“当用户处理论文时”精确得多。

5.2 输出格式不符合预期

这个问题通常出在 Prompt 或规则不够具体。我一般会：

• 在 SKILL.md 里加一个“输出示例”，让模型有参照。
• 在 Prompt 里明确“不要做什么”，比如“不要添加额外解释”“不要修改原文术语”。
• 用后处理脚本做格式校验，不合格就重试或报错。

有一次我做一个表格提取 Skill，模型总是把表格转成段落。后来我在 Prompt 里加了“必须保留 Markdown 表格语法，包括表头和分隔行”，问题就解决了。所以负面约束有时候比正面描述更有效。

5.3 MD 文件解析出错

MD 文件看起来简单，但解析起来坑不少。常见问题包括：

我一般会在 Skill 里加一个预处理步骤，用markdownlint先校验一遍，把格式问题修掉再进入正式流程。这一步看似多余，但能省掉后面很多麻烦。

5.4 Prompt 被标记为违规或闪退

热词里提到“invalid prompt: your prompt was flagged as potentially violating our usage p”和“+prompt闪退”，这在实际操作中确实会遇到。我的处理原则是：

• 检查 Prompt 里是否有敏感词或歧义表达，尽量用中性、具体的描述。
• 避免在 Prompt 里写可能被误解为指令注入的内容。
• 如果平台有 Prompt 长度限制，把长 Prompt 拆成多个短 Prompt 分步执行。
• 闪退问题通常和内存或超时有关，减少单次处理的输入量，或者增加超时设置。

提示：写 Prompt 时尽量用“请执行以下操作”而不是“你必须”“立刻”这类强硬措辞，前者更稳定，后者容易触发风控。

5.5 Skill 执行速度慢

如果 Skill 跑一次要等很久，可以从这几个方面优化：

• 减少不必要的步骤，能合并的合并。
• 把串行改成并行，比如多个独立字段的提取可以同时进行。
• 缓存中间结果，避免重复计算。
• 用更小的模型处理简单步骤，复杂步骤再用大模型。

我之前有一个 Skill 处理一份文档要两分钟，后来把“格式校验”和“字段提取”并行化，时间直接降到四十秒。所以优化前先分析瓶颈在哪，别盲目改。

6. 认知总结：我从折腾 Skill 中学到了什么

6.1 Skill 的本质是“可复用的思考过程”

用了这么久 Skill，我最大的体会是：Skill 不只是技术工具，它其实是你思考过程的固化。你写一个 Skill，本质上是在回答“这件事应该怎么做”的问题。规则越清晰，说明你想得越清楚；规则越模糊，说明你自己还没想明白。

所以我现在写 Skill 之前，会先用手写一遍流程，确认每一步都明确无误，再开始写文件。这个习惯让我少走了很多弯路。

6.2 好的 Skill 是迭代出来的，不是设计出来的

我见过很多人想一次写出完美的 Skill，结果卡在第一步。我的建议是：先写一个能跑的版本，哪怕很粗糙，然后在实际使用中不断改。真实场景会暴露你想象不到的问题，这些问题才是改进的方向。

我自己的paper-summarySkill 改了七版，从最初只能处理标准结构论文，到现在能处理各种变体，全靠一次次踩坑和修正。所以别怕改，改得越多，Skill 越稳。

6.3 Prompt 工程是 Skill 的基础功

Skill 里的 Prompt 写得好不好，直接决定输出质量。我总结了几条 Prompt 编写原则：

• 具体优于抽象：说“提取三句话”比说“提取关键信息”好。
• 示例优于描述：给一个输入输出示例，比写一段规则更有效。
• 约束优于自由：明确“不要做什么”，比只说“要做什么”更可控。
• 分步优于一步：复杂任务拆成多个 Prompt，比一个长 Prompt 稳定。

这些原则不仅适用于 Skill，也适用于日常和模型打交道。练好 Prompt 工程，Skill 自然就写得好。

6.4 工具是辅助，思路是核心

VS Code、Typora、Obsidian 这些工具确实能提升效率，但工具不是关键。关键是你能不能把任务拆清楚、把规则写明白、把流程串起来。工具只是帮你把想法落地的载体。

我见过用记事本写 Skill 也写得很好的人，也见过工具一堆但 Skill 一团糟的人。所以别在工具上纠结太久，先把思路理清楚，工具够用就行。

6.5 最后分享一个小技巧

如果你刚开始学 Skill，不知道从哪下手，我建议你找一个自己每周都要做的重复任务，把它做成 Skill。不用追求完美，能跑就行。做完之后你会发现，你对这个任务的理解比以前深了很多，而且下次再做类似的事情，你会自然而然地想“这个能不能也做成 Skill”。

这种从“手动做”到“定义怎么做”的转变，才是 Skill 带给我最大的收获。它让我从执行者变成了设计者，从“做完这件事”变成了“设计一套能反复做好这件事的系统”。这个思维方式的变化，比任何具体技术都值钱。