# 拆skill-creator：八个模式写首Skill ## 概述 本期是本栏目第8轮观察，轮次主题是设计模式提炼：不追本周新面孔，回头拆一个所有新面孔都绕不开的源头——官方的 skill-creator，一个专门用来造 Skill 的 Skill。市场目录里几千个第三方 Skill，骨架大多照着官方字帖描，而这张字帖的权威版本就是它。本文材料为本机安装的官方发行版全文（`~/.claude/skills/skill-creator/`），逐段拆到「每一行为什么这么写」，最后提炼出八个可以直接照抄的 SKILL.md 写法模式，并给出写你自己第一个 Skill 的最小路径。核心发现先说：它最值钱的部分不是「怎么创建」，而是它对「什么会让一个 Skill 失效」的判断——不触发、过拟合、指令堆砌，三个坑全在正文里点了名。 ## 一、为什么是它：所有字帖的祖版 Skills 生态现在有两层：上面是 skillsmp.com、skills.sh、mcpservers.org/agent-skills 这些聚合市场里流转的分发层，下面是极少数定义「一个 Skill 长什么样」的规范层。规范层的活标本就在 anthropics/skills 官方仓库里，而 skill-creator 是仓库里唯一一个「以 Skill 为原料」的 Skill——它教 Claude 写 Skill、测 Skill、改 Skill、打包 Skill。 它是元需求。本会话环境里，skill-creator 至少以三个发行版本并存：独立版 `skill-creator`、示例合集里的 `example-skills:skill-creator`、obsidian 插件包里的 `obsidian:skill-creator`。官方把「教人造 Skill」这件事分发了三遍，说明这不是众多品类之一，而是生态的入场发牌员。想自己写 Skill，最短的路不是读二手教程，而是看这张祖版字帖本身怎么写的。 ## 二、先看目录：一个成熟 Skill 的解剖图 skill-creator 正文里给出的标准解剖结构，值得整段抄下来： ``` skill-name/ ├── SKILL.md (必选) │ ├── YAML frontmatter (name, description 必填) │ └── Markdown 指令正文 └── 捆绑资源 (可选) ├── scripts/ - 确定性、重复性任务的可执行代码 ├── references/ - 按需载入上下文的文档 └── assets/ - 产出时要用的文件（模板、图标、字体） ``` 三个可选目录的分工是一句话级的：**算得出来的给脚本，偶尔要查的给参考，交稿要带的给资产**。它自己则示范了一个「重度形态」——除了上述目录，还多了 `agents/`（grader、comparator、analyzer 三个子代理的说明书）和 `eval-viewer/`（评测结果查看器脚本）。也就是说，Skill 的上限不是一个提示词文件，而是一套自带工具链的小型软件包。这是生态里「胖 Skill」的合法形态，前提是三层渐进披露撑得住（见模式二）。 ## 三、逐段拆：SKILL.md 里每个设计动作的意图 以下全部基于本机发行版原文，按出场顺序。 **1. 开头先给流程地图，不给命令。** 正文第一屏是一段高层流程：定意图 → 写草稿 → 造测试用例 → 带着技能跑 → 和用户一起评 → 按反馈改 → 循环。紧接着一句关键指令：「你的工作是判断用户处在这个流程的哪一步，然后跳进去帮忙」。这是在告诉执行模型：**先定位入口，再动手**。用户可能带着半成品来，可能只要走评测环节。写 Skill 时先画流程地图、再声明「你要自己判断从哪进入」，是防呆的第一道闸。 **2. 对话风格段：提示词要考虑「模型面对的是谁」。** 它专门写了一节 Communicating with the user，提醒执行模型用户可能是「被 Claude 打动、正在打开终端的水管工，正在搜 how to install npm 的祖父母」，也可能是老手——JSON、assertion 这类词要等用户表现出听懂了再用。这一节解决的是 Skill 作者最容易忘的事：你的指令是写给模型的，但模型的输出是给人看的，**受众画像本身要写进指令**。 **3. 捕捉意图四问。** 要做什么、什么时候该触发、期望输出格式、要不要建测试用例。第四问里藏着一个重要分流：**输出可客观验证的技能（文件转换、数据抽取、固定流程）值得配测试；输出主观的（文风、美术）不硬配**。这直接决定了你写完 Skill 之后要不要进评测循环。 **4. description 是唯一的门牌，规则有三条。** 原文写得非常直白：description 是「primary triggering mechanism（首要触发机制）」，要同时写清做什么和什么场景用，并且——「All ‘when to use’ info goes here, not in the body（所有『何时使用』的信息放这里，不放正文）」。第三条是针对现实的修补：模型目前倾向于「不触发（undertrigger）」，所以描述要写得主动一点（pushy）。原文给的对比例子值得整段抄： > 弱：How to build a simple fast dashboard to display internal Anthropic data. > 强：同上，再加一句——只要用户提到 dashboard、数据可视化、内部指标，或者想展示任何公司数据，**哪怕他们没明说「dashboard」这个词**，都务必使用本技能。 这三条合起来就是模式一。 **5. 渐进披露三层，带预算。** 原文给数字：元数据（name+description）常驻上下文，约 100 词；SKILL.md 正文触发时全量进上下文，理想 500 行以内；捆绑资源按需加载，不限量，**脚本甚至可以不加载进上下文就直接执行**。配套两条工程纪律：逼近 500 行就「再加一层层级，并写清指路的话」；超过 300 行的大参考文件必须带目录。多域支持时按域拆参考文件——原文的例子是 `cloud-deploy/` 下 `references/aws.md、gcp.md、azure.md`，Claude 只读相关的那份。 **6. 不惊讶原则。** 原文单列一节 Principle of Lack of Surprise：Skill 不得包含恶意代码、漏洞利用代码，内容不得与描述的意图相悖；同时明确「角色扮演类是 OK 的」。这条后来成了各 Skills 目录安全扫描的基本盘，而它的出处就在这里。 **7. 写作风格：讲理，不喊令。** 这是全文我认为最值钱的一段，几乎可以当提示词工程的诫律读： > 优先解释「为什么这件事重要」，而不是堆砌生硬的 MUST。如果你发现自己在用全大写写 ALWAYS 或 NEVER，那是黄旗——尽量改成讲清理由，让模型理解这件事为什么重要。 配套还有：指令用祈使句；输出格式给出精确模板；例子按「输入/输出」成对给。以及那条对作者自己的忠告：写完初稿，「用 fresh eyes 重新看一遍再改」。 **8. 评测段的工程细节，处处是防污染设计。** 带技能跑和不带技能跑（baseline）必须在同一轮发车，「不要先发带技能的再回来补基线」——防止时间差引入变量。baseline 有两种语义：新建技能时 baseline 是「无技能裸跑」；改进旧技能时 baseline 是「旧版快照」，改之前先 `cp -r` 存快照。打分结果 `grading.json` 的字段名被钉死为 `text/passed/evidence`，因为查看器依赖这些精确字段。计费和耗时数据（total_tokens、duration_ms）只随任务通知出现一次，「这是唯一的捕获机会」——收到就要立刻落盘。这些细节说明一件事：**Skill 评测本身就是一门要有实验纪律的活**。 **9. 泛化警告：为百万次运行写，不为眼前例子写。** 改进环节的核心段落：在几个测试用例上来回迭代只是为了快，但成品要被用一百万次；如果只对这几个例子有效，它就是废物。反模式点名两类：「fiddly overfitty changes（琐碎的过拟合式修补）」和「压迫性约束」。给出的替代手段很妙：遇到顽固问题，「换个比喻、换一种工作方式，比加约束更便宜」。同段还有那句在社区流传很广的自我调侃——「我们可是想在这里每年创造几十亿美元价值的，你的思考时间不是瓶颈，慢慢想」。 **10. 重复第三次，就收编成脚本。** 教你读 transcript 而不只看产出：如果三个测试用例里，子代理都各自独立写出了一个 `create_docx.py`，「这是强烈信号——这个脚本应该被写一次、放进 scripts/、让技能直接调用」。这是模式六的原文依据：**Skill 是高频重复劳动的沉淀层，第三次重复就是收编信号**。 **11. 描述优化闭环，一段完整的小型机器学习流程。** 流程是：造 20 条触发评测查询（一半应触发、一半不该），60/40 切训练/保留测试集，每条查询跑 3 次取触发率，让 Claude 依据失败案例改写描述，最多迭代 5 轮，**最终按测试集分数而非训练集分数选出 best_description**——原话是「avoid overfitting（防过拟合）」。负例的设计纪律尤其值得抄：最有价值的负例是 near-miss（差一点命中）——和技能共享关键词但实际需要别的东西；像拿「写个斐波那契函数」去当 PDF 技能的负例，「太简单了，什么也测不出来」。 **12. 触发机制的机制层真相。** 原文顺带讲破了触发原理：技能以 name+description 出现在模型的 available_skills 列表里，模型据此决定是否查阅；但**模型只在「自己不容易搞定的任务」上才会咨询技能**——「读这个 PDF」这种一步任务，描述写得再好也不触发。这条真相直接决定你该怎么写触发测试：评测 query 必须是有分量、多步骤的真实请求，原文甚至给了好坏对比——坏的：「Format this data」；好的：带文件名（“Q4 sales final FINAL v2.xlsx”）、带列位置、带背景故事的一整段大白话。 ## 四、八个模式：抄走就能用 把上面的逐段拆解收敛成八条可操作模式： | # | 模式 | 治什么病 | 原文落点 | 先抄指数 | |---|------|---------|---------|---------| | 1 | 门牌大于正文 | 描述含糊导致永不触发 | when-to-use 全进 description，写得 pushy | ★★★★★ | | 2 | 三层卸货 | 正文超载、上下文爆炸 | 100词/500行/无限 三层预算 | ★★★★★ | | 3 | 讲理不讲令 | 满屏 MUST 模型反而僵硬 | 全大写 ALWAYS/NEVER 是黄旗 | ★★★★☆ | | 4 | 重复即脚本 | 每次现造轮子 | transcript 里第三次重复就进 scripts/ | ★★★★☆ | | 5 | 负例要刁钻 | 自我测试全是送分题 | near-miss 负例 + 任务要够重才会触发 | ★★★★☆ | | 6 | 先地图后路 | 模型上来就蛮干 | 开头画流程，声明「先定位再动手」 | ★★★☆☆ | | 7 | 过拟合防火墙 | 只对测试例子有效 | 按测试集选优；换比喻优于加约束 | ★★★☆☆ | | 8 | 说话看人 | 输出对不上受众 | 受众画像写进指令 | ★★★☆☆ | 三张图辅助理解。第一张是渐进披露的加载路径： ```mermaid flowchart TD A["用户说了一句话"] --> B["第一层：门牌"] B --> B1["name 加 description"] B1 --> B2["常驻上下文约百词"] B2 --> C{"命中触发"} C -->|是| D["第二层：正文"] C -->|否| Z["不加载"] D --> D1["SKILL.md 全文"] D1 --> D2["五百行以内"] D2 --> E{"还要更多细节"} E -->|是| F["第三层：附件"] E -->|否| G["照正文直接干"] F --> F1["references 按需读"] F --> F2["scripts 直接跑不读入"] F --> F3["assets 交稿带上"] ``` 第二张是最小可行评测环——你不一定要像官方那样上子代理和查看器，但「带技能跑、不带技能跑、对照改」这个最小环应该保住： ```mermaid flowchart TD S1["写草稿"] --> S2["备两三句真话测试"] S2 --> S3["带技能跑一遍"] S3 --> S4["不带技能跑基线"] S4 --> S5["对照找差距"] S5 --> S6{"达标了吗"} S6 -->|否| S1 S6 -->|是| S7["收编脚本再打包"] ``` ## 五、动手：你的第一个 Skill，照抄这份骨架 按模式一、二、六，最小 Skill 只需要三步。 **第一步：建目录。** 个人级技能放 `~/.claude/skills/你的技能名/`，团队共享放仓库的 `.claude/skills/你的技能名/`。本机所有技能的实际安装位置就是 `~/.claude/skills/`。 **第二步：写 SKILL.md。** 以一个「周报整理」技能为例，骨架如下——注意 description 是怎么按 pushy 原则写的： ```markdown --- name: weekly-report description: 把零散工作记录整理成结构化周报。只要用户提到周报、 weekly、本周汇总、周五要交的汇报，或者贴来一堆散乱的 todo、 会议纪要、bug 清单想归拢成一段汇报，就用本技能—— 哪怕用户没说出「周报」两个字。输出固定含三段：本周进展、 风险与阻塞、下周计划。 --- # 周报整理 先判断用户给的材料属于哪类：流水账、会议纪要、还是待办清单， 不同入口对应不同归拢方式。 ## 输出格式 固定用这个模板： # 周报 ## 本周进展 ## 风险与阻塞 ## 下周计划 ## 写作原则 周报的读者是管理者，要的是结论与风险，不是过程。所以先写结果， 再补证据；不确定的进度标注「待确认」而不是猜一个百分比。 （解释为什么，而不是规定字数和感叹号。） ``` 细节都在照模式走：门牌写满触发词与近义词（模式一）；正文不到三十行，格式模板精确、风格只讲理不喊令（模式三）；「先判断材料类型」是先地图后路（模式六）。 **第三步：两句话自测。** 不用官方那套完整评测，最低配版照模式五来：准备一句会触发的（「把这段乱糟糟的记录归拢成周五交的东西」）和一句 near-miss 不该触发的（「帮我写一份周报模板给团队统一格式用」——用户要的是空模板不是整理内容）。新开一个会话各说一遍，看它触不触发、格式对不对，不对就改 description 和正文，再跑。这就是官方「草稿→测试→反馈→再改」闭环的家用简化版。 等你的技能用顺了，留意模式四的信号：如果每次用它你都要手动做同一个动作（比如先把记录按项目分组），那就把这个动作写成脚本放进 `scripts/`，正文里改一句「先运行该脚本」。 ## 六、排行榜与结论 按「写第一个 Skill 时的取用顺序」排名： 1. **门牌大于正文**——不触发，一切白搭；这是 skill-creator 唯一动用了「务必（pushy）」这种口吻的地方。 2. **三层卸货**——决定技能能否长大而不撑爆上下文；500 行警戒线和按域拆参考是硬纪律。 3. **讲理不讲令**——直接决定模型执行质量；黄旗自检法（搜一遍你的全大写）一分钟就能做完。 4. **重复即脚本**——技能从「提示词」进化为「工具」的分水岭。 5. **负例要刁钻**——测不出来比不测更危险；near-miss 意识同样适用于日常提示词调试。 6. **先地图后路**——多入口流程的必备声明。 7. **过拟合防火墙**——技能做大之后的护城河，新手可以先记结论：换比喻优于加约束。 8. **说话看人**——面向人的输出型技能加分项。 一句话收束：skill-creator 的正文表面上是一部创建手册，实际是一部失效案例集——它对「描述写含糊会永不触发」「正文写太满会撑爆上下文」「全大写会把模型喊僵」「围着测试例子改会过拟合」的每一处点名，都比任何正面教程更接近 Skills 这门手艺的本质。本周市场上还会有新面孔上架冲榜，但想自己下场写一个，先把它这八条抄走，你的第一个 Skill 就不会是凭感觉堆出来的那一种。 ## 参考来源 1. [anthropics/skills 官方仓库](https://github.com/anthropics/skills) — skill-creator 及官方示例 Skill 的上游发行仓库 2. 本机安装的 skill-creator 官方发行版（`~/.claude/skills/skill-creator/`，含 SKILL.md、agents/、references/schemas.md、eval-viewer/）— 本文逐段拆解的一手文本，所有引文均出自该文件 3. [skillsmp.com](https://skillsmp.com)、[skills.sh](https://skills.sh)、[mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — Skills 聚合目录，用于观察「官方骨架成为第三方默认字帖」这一生态现象（本文未引用其具体榜单数据） > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。