拆解一个成熟 Skill，看懂 Skill 到底该怎么写

很多人写 Skill，第一反应是把一段提示词塞进 SKILL.md。

这样当然能用，但它离成熟还差一截。一段提示词只交代了"要做什么"，而成熟的 Skill 还得交代"该怎么做"：什么时候触发、按什么流程走、遇到模糊的地方依据什么规则、哪些动作可以固化下来，不再靠模型每次临场发挥。

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

text 复制代码

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

SKILL.md 是必选的，其余都按需要添加。Skill 是什么、基本结构、如何创建，我在上一篇《一篇讲清 Agent Skills：把经验变成可调用的能力》里系统讲过。

先看一个常见的"不成熟"写法：

假设我们要做一个"想法捕获"的 Skill：把用户脑子里一堆想法、任务和灵感，整理成一份清单。很多人会这样写：

markdown 复制代码

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

这段话意思清楚，但只是把一段提示词放进了 SKILL.md：说了目标，没说该怎么做到。

继续补提示词也不够。输入怎么处理、原意怎么保留、内容怎么分拣、要不要结合项目上下文，都得有明确做法。

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

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

这个 Skill 做的正是上面那件事：你把一堆乱想法倒给它，它会整理成结构化清单。

出自 alirezarezvani/claude-skills 这个开源 Skill 合集（MIT 协议，1.8 万+ star）。选它，是因为场景人人都懂、目录分工清楚、脚本也不涉及晦涩逻辑，正适合拿来观察一个成熟 Skill 怎么写。

源码位置：

GitHub 仓库：alirezarezvani/claude-skills

目录：productivity/capture/skills/capture

它的目录长这样：

text 复制代码

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 沉淀的是一类任务的可复用工作流。

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

公众号：澄旭