拆解成熟Skill：写法技巧与案例详解

许多人在编写 Skill 时，习惯直接往 SKILL.md 里塞一段提示词。

这样当然能用，但距离一个生产级别的 Skill 还差得远。一段提示词只说明了“要做什么”，而成熟的 Skill 还必须定义清楚“该怎么做”：什么条件下触发、按什么流程执行、遇到歧义时依据什么规则、哪些操作可以固化为脚本，无需每次让模型临时发挥。

先对齐一下 Skill 的文件结构。本质上它是一个文件夹：

my-skill/
├── SKILL.md          # 必选：入口与主流程
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：按需查阅的规则与资料
├── assets/           # 可选：模板、图片等素材
└── ...

SKILL.md 是唯一必需的，其余目录按需添加。关于 Skill 是什么、基本结构、如何创建，我在上一篇《一篇讲清 Agent Skills：把经验变成可调用的能力》中已经系统梳理过，此处不再赘述。

先看一个常见的“不成熟”写法。

假设我们要实现一个“想法捕获”的 Skill：把用户脑中零散的想法、任务、灵感整理成一份清单。很多人会这样写：

当用户输入一堆想法、任务和灵感时，帮他整理成清晰的项目、待办事项和下一步计划。
尽量保留原意，不要遗漏信息。

这段话意思明确，但本质就是把一段提示词放进了 SKILL.md：只说了目标，没交代具体怎么实现。

继续往里面堆提示词也不行。输入如何解析、原意如何保留、内容如何分拣、是否结合项目上下文，都需要明确的实现方式。

成熟写法长什么样？来看一个真实的开源 Skill。

开源 Skill：Capture Skill（想法捕获）

这个 Skill 做的正是上面那件事：用户将一堆杂乱想法丢进来，它返回结构化的清单。

它来自 alirezarezvani/claude-skills 这个开源 Skill 合集（MIT 协议，1.8 万+ star）。选择它是因为场景通俗易懂、目录分工清晰、脚本逻辑不复杂，很适合用来观摩一个成熟 Skill 的写法。

它的目录结构如下：

capture/
├── SKILL.md
├── references/
│   ├── complexity_matching.md
│   ├── voice_preservation.md
│   └── workspace_detection.md
└── scripts/
    ├── complexity_estimator.py
    ├── dump_classifier.py
    └── workspace_inventory.py

一个 SKILL.md，加上 references/、scripts/ 各三个文件。

SKILL.md：入口与主流程

Skill 不会一开始就把所有内容塞进上下文，而是按需展开：先读取入口，再根据任务读取其他文件。SKILL.md 分为两部分：开头的 --- 之间是 frontmatter（元数据），下面是正文。

首先是 description：既要说明做什么，也要说明何时使用。

description 是 frontmatter 中的字段，决定了 Agent 何时调用该 Skill。很多人只把它当作自我介绍（“一个帮用户整理想法的 Skill”），结果 Agent 看到输入却不知道是否该触发。

Capture Skill 的 description 更像一个触发条件说明。它列举了十多种用户可能的说法，例如 capture this、brain dump 等；换成中文场景就是“帮我理一理”“我先把想法记下来”“脑子一团乱”。

它还定义了隐式信号：即使用户没有说出关键词，只要丢上来一大段混杂的想法，也应触发。边界也标明了：用户已经把想法发过来，本身就是请求，不必再询问“要我整理吗”。

正文先写操作原则。这些是整理时的底线：

• 全部捕获、零丢失：不要丢弃任何看起来“不重要”的内容；
• 保留用户原话：不要整理成官腔、磨平原意；
• 输出繁简匹配输入：不要只有三句话也硬套四个板块；
• 对模糊点诚实：不要遇到看不懂的就硬猜；
• 未经许可不行动：不要整理完擅自执行某条任务。

然后规定输出格式。默认分成四个板块：项目与想法、任务、关联、我能帮什么；末尾再问一句“先做哪个？”。输入很轻时，就压缩成更短的结构。

正文负责调度，不负责装下所有材料。 至此，SKILL.md 已经交代了触发条件、操作原则和输出结构。再往下，更细的判断标准和更稳定的执行动作就应该拆分出去：

• 需要模型判断的规则，放进 references/，例如如何保留原意、如何判断繁简、如何核对上下文；
• 可以机械执行的动作，放进 scripts/，例如估算输入复杂度、给内容打标签、扫描工作区。

所以 SKILL.md 更像是入口和主流程：让 Agent 知道何时调用、按什么顺序执行、需要时去哪里查阅资料或调用脚本。

references/：存放按需查阅的长资料

references/ 通常存放篇幅较长、不必每次完整读取的资料，例如 API 文档、公司规范、字段说明、典型案例。在 Capture Skill 中，它存放的是几份判断标准：如何保留原意、如何判断输出繁简、如何核对工作区关联。

• voice_preservation.md 界定“保留原话”的边界：改错别字、将“我应该发邮件给小王”顺成“发邮件给小王”，可以；将“找小王聊聊那事儿”改成“就相关事项与小王安排对齐”，就过头了。
• complexity_matching.md 说明何时使用完整版、何时压缩：条目多且能聚类成主题就用完整四板块，三五条且不相关就压缩。
• workspace_detection.md 规定如何核对工作区上下文：如果在命令行环境，就查本地文件；如果在带项目资料的网页环境，就查项目文件；如果连了 Notion、Drive、GitHub 等外部工具，就用对应工具搜索。什么都查不到，就说明限制，不要编造关联。

scripts/：存放可稳定执行的动作

有些步骤每次都一样，但让模型判断容易遗漏。写成脚本，结果一致、可复用，也少占上下文。

脚本不一定要手写。把业务场景说清楚：要处理什么、边界在哪、输入输出格式，AI 就能帮你写。例如，告诉它“先数一数有多少条，再判断是否需要用完整版输出”，它就能把这一步做成一个小脚本。

• complexity_estimator.py 计算条目数量、检测同一关键词是否反复出现（聚类信号），提供“完整还是压缩”的建议，作为“繁简匹配”的依据。
• dump_classifier.py 使用正则给每行预打标签：任务、决定、疑问、想法、项目组件、上下文。它只是初稿（脚本中注明是启发式的，模型可以推翻），但先把第一轮分拣完成大半。
• workspace_inventory.py 扫描文件名、搜索内容，只返回真实命中。这样做是为了避免模型凭空编造不存在的文件：拿到的是事实，不是想象。

这三个脚本都不调用大模型。它们执行的是计数、正则分类、文件扫描这类确定性操作，结果稳定，也方便复查。

写 Skill 时，目录如何分工

从 Capture Skill 回到通用写法，目录分工可以归纳为以下几点。这也符合官方文档中的组织方式：入口优先读取，其余材料按需查阅、调用或使用。

• SKILL.md 存放每次都要阅读的核心说明：用途、触发条件、主流程、关键原则，以及何时去读 references/、何时调 scripts/。它一旦被触发就整体读进上下文，太长会稀释主流程。官方文档建议接近 500 行时就考虑拆分。Capture Skill 放进去的就是 description、五条操作原则、四板块输出，以及需要时去读哪些 reference、调用哪些 script。
• references/ 存放长资料和判断标准：篇幅较长、需要模型参考、但不必每次完整读取。Capture Skill 的 voice_preservation.md、complexity_matching.md、workspace_detection.md，都是展开后较长、也不是每次必用的判断标准。
• scripts/ 存放稳定步骤：校验、转换、提取、扫描这类每次做法一样、结果相对确定的动作。需要大量语义判断的场景，结果难以固定，就不适合硬写成脚本。Capture Skill 的三个脚本都是计数、正则、扫描，不调大模型，每次结果一致。
• assets/ 存放静态素材：模板、样例、图片等文件；Capture Skill 没有用到，可以按需添加。

有些问题会同时用到 references/ 和 scripts/。例如 Capture Skill 的“繁简匹配”和“找关联”：references/ 提供判断标准，scripts/ 提供事实依据。

自己写 Skill，可以从这几个问题入手

不要一开始就把目录建全。Capture Skill 是成品，自己写不必照搬它的规模。先把 description 和一个最小的 SKILL.md 做出来，让它能用起来；使用几次之后，再根据需要补充 references/、scripts/ 和 assets/。

先做一个能用的版本：

• 它做什么、何时触发？写入 description。
• 每次按什么流程走、有哪些原则？写入 SKILL.md。

跑过几次，缺什么补什么：

• 哪类资料或判断标准写细了会很长？放进 references/。
• 哪些步骤每次做法一样、结果相对确定？写成 scripts/。
• 有固定的模板、样例、图片素材吗？放进 assets/。

总结

回头再看开头那段提示词。要把它变成一个成熟的 Skill，不是继续往 SKILL.md 里堆细节，而是先把这类任务的工作流设计清楚：

写 Skill 时，真正要设计的是这套工作流：什么时候触发，按什么流程处理，哪些规则需要查阅，哪些步骤可以交给脚本固化。