很多人在编写 Skill 时，第一反应就是把一段提示词塞进 SKILL.md 文件。

这样做虽然也能用，但离一个成熟的 AI 技能还差得很远。一段提示词仅仅交代了“要做什么”，而完善的 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 时，真正要设计的是这套工作流：什么时候触发，按什么流程处理，哪些规则需要查阅，哪些步骤可以交给脚本稳定执行。