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 的第一步不是写文件而是拆需求。我一般会问自己四个问题这个任务重复出现的频率有多高如果一周用不到一次可能不值得做成 Skill。任务的输入输出是否稳定如果每次输入格式都不一样Skill 的规则就很难写。任务是否可以拆成明确的步骤步骤越清晰Skill 越好写。有没有现成的 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 什么时候该改 SkillSkill 不是写完就一劳永逸的。我一般在这几种情况下会回去改输出不稳定同样的输入有时候输出好有时候输出差。这通常是规则不够具体或者 Prompt 有歧义。新场景出现原来只处理中文论文现在要处理英文论文需要加规则。效率瓶颈某个步骤太慢或太耗资源需要优化。依赖变化外部工具升级或接口变了Skill 要跟着改。我印象最深的一次修改是一个文档处理 Skill 在处理超长文件时总是截断。排查后发现是 Prompt 里没有限制输入长度模型自动截断了。后来我在 SKILL.md 里加了“如果输入超过 8000 字先分段处理再合并”的规则问题就解决了。4.2 修改 Skill 的正确姿势改 Skill 最忌讳的是直接在生产环境改。我的做法是复制一份到dev/目录在副本上改。准备一组测试用例覆盖正常情况和边界情况。对比修改前后的输出确认改进有效且没有引入新问题。记录修改原因和效果写在CHANGELOG.md里。确认无误后再合并回主目录。这套流程看起来麻烦但能避免“改了一个地方崩了三个地方”的惨剧。尤其是当多个 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 文件看起来简单但解析起来坑不少。常见问题包括问题原因解决方法标题层级错乱跳级使用标题如从 H2 直接到 H4统一按 H2→H3→H4 顺序列表项丢失缩进不一致统一用 2 或 4 空格缩进代码块被误解析缺少语言标注或反引号不匹配代码块必须标注语言反引号成对表格渲染失败分隔行格式错误确保分隔行有至少三个连字符我一般会在 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 带给我最大的收获。它让我从执行者变成了设计者从“做完这件事”变成了“设计一套能反复做好这件事的系统”。这个思维方式的变化比任何具体技术都值钱。
