拆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”）、带列位置、带背景故事的一整段大白话。

四、八个模式：抄走就能用

把上面的逐段拆解收敛成八条可操作模式：

三张图辅助理解。第一张是渐进披露的加载路径：

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 交稿带上"]

第二张是最小可行评测环——你不一定要像官方那样上子代理和查看器，但「带技能跑、不带技能跑、对照改」这个最小环应该保住：

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 原则写的：

---
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 官方仓库 — skill-creator 及官方示例 Skill 的上游发行仓库
2. 本机安装的 skill-creator 官方发行版（~/.claude/skills/skill-creator/，含 SKILL.md、agents/、references/schemas.md、eval-viewer/）— 本文逐段拆解的一手文本，所有引文均出自该文件
3. skillsmp.com、skills.sh、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 等场景全覆盖。