# 拆解官方skill-creator：动手写你的第一个Skill
## 概述
Skill 生态跑了七轮拆解，横评过元工具、拆过几十个热门 Skill，但一直没有正面攻克那篇“所有 Skill 的母文”——Anthropic 官方的 **skill-creator**。它随 example-skills 插件分发（本机缓存路径 `/root/.claude/plugins/cache/anthropic-agent-skills/example-skills/`，仓库为 github.com/anthropics/skills），定位是“用来造 Skill 的 Skill”。本期把它当解剖标本，逐段精读它的 SKILL.md 是怎么写的：它如何设计三层渐进披露、如何用 A/B 基线测试来验证一个 Skill 好不好用、如何把机器学习里“训练集/测试集防过拟合”的思路用在优化一行 description 上。文章最后把这些手法收敛成五条可直接照抄的军规，并给出从零写出你自己第一个 Skill 的最短路径。本文引用的片段全部来自 skill-creator 原文（经本会话完整加载核实），未核实的数据一律不写。
## 一、它的生态位：Skill 供应链的“ compiler ”
之前拆过的元工具（find-skills 负责“找”、skill-factory 负责“批量造”、skill-sync-github 负责“同步”）各占一段供应链。skill-creator 占的是最关键的一段：**把一个模糊想法变成一个经过测试、可打包分发的 Skill 的完整流水线**。它的开头第一句就给出了全流程鸟瞰：
> Decide what you want the skill to do → Write a draft → Create a few test prompts and run claude-with-access-to-the-skill → Help the user evaluate the results → Rewrite based on feedback → Repeat → Expand the test set
注意这个顺序：**先写草稿、再跑真实测试、再看反馈迭代**。它没有把“写 SKILL.md”当成重心，而是把“验证 SKILL.md 有没有用”当成重心。这是它和社区绝大多数“模板型”写 Skill 教程的根本分歧——后者教你格式，它教你闭环。
```mermaid
flowchart LR
A[捕获意图 Capture Intent] --> B[访谈+调研 Interview]
B --> C[写 SKILL.md 草稿]
C --> D[并行跑测试: with_skill vs baseline]
D --> E[打分 grading.json]
E --> F[聚合 benchmark + 生成评审页面]
F --> G[用户反馈 feedback.json]
G --> H{满意?}
H -- 否 --> C
H -- 是 --> I[触发词优化 loop]
I --> J[打包 .skill 文件]
```
## 二、逐段拆解：每一处设计都在解决一个具体问题
### 2.1 开篇的“地图先行”与一句 "Cool? Cool."
正文第一段用六行把整个流程讲完，然后才展开细节。这符合官方自己推的渐进披露原则：模型（和人）先要一张地图，才知道当前这段指令处在流程哪个位置。
更有意思的是流程讲完后的那句口语：*"Cool? Cool."*。看似闲笔，实则是刻意的语气设计。skill-creator 后文明确警告不要写满 "musty MUSTs"（发霉的 MUST），通篇用商量式口吻代替命令式——"you can do that instead"、"the order is flexible"。对模型来说，命令式长文容易诱发机械执行，而对话式语气让模型保持对真实语境的判断力。**语气本身就是提示词工程的一部分**，这是它教的第一课。
### 2.2 Communicating with the user：把“受众检测”写进指令
它专辟一节讲“怎么跟用户说话”，并给了具体标尺：*“evaluation 和 benchmark 边缘可接受；JSON、assertion 这类词，要先看到用户懂行的信号再用”*。还配了一段时代观察——水管工开始打开终端、爷爷奶奶开始搜“怎么装 npm”。
这解决的是 Skill 的一个真实痛点：**同一个 Skill 会被完全不同水平的人触发**。写死一种说话风格必然劝退一半用户。给模型一条“看语境线索调行话密度”的元规则，比枚举用户画像便宜得多。
### 2.3 Capture Intent：对话史也是一种输入源
第一步不是问用户，而是：如果当前对话里已经存在一个用户想固化的工作流（比如用户说“把这个流程做成 skill”），**先从对话历史里提取**——用了哪些工具、什么步骤顺序、用户纠正过什么、输入输出格式长什么样。提取完再让用户补缺口、确认。
这是很多新手写 Skill 时完全想不到的一层：Skill 的输入不只有用户的这句话，还有**整个会话的上下文**。会话史里藏着最真实的“用户到底要什么”，比重新访谈准确。
### 2.4 description 的“推式写法”：官方自曝 undertrigger 问题
在“写 SKILL.md”一节，官方给了一条非常坦白的指导：
> 目前 Claude 倾向于 undertrigger——明明该用却不用。为了对抗这一点，description 要写得“推”一点。
并给了直接可抄的对照例：不写 *"How to build a simple fast dashboard to display internal Anthropic data"*，而写 *"……Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, **even if they don't explicitly ask for a 'dashboard'**"*。
拆开看这个句式由三部分组成：**做什么 + 触发词枚举 + 兜底从句（“即使用户没说出那个词”）**。第三部分是精髓——它把“同义词场景”全部收编进触发域。这解释了为什么总榜上那些安装量大的 Skill，description 普遍写得“啰嗦”：啰嗦是故意的。
同时它规定“所有 when-to-use 信息只放 description，不放正文”——因为 description 是唯一常驻上下文的层（约 100 词），正文触发时才加载，放错位置等于永远不被读到。
### 2.5 三层渐进披露：Skill 的“内存管理”架构
官方给出的标准目录结构与加载模型：
```
skill-name/
├── SKILL.md (必需: frontmatter + 指令正文)
└── 可选资源
├── scripts/ 可执行脚本——确定性/重复性任务
├── references/ 参考文档——按需载入上下文
└── assets/ 输出用资产——模板、图标、字体
```
三层加载：**元数据常驻（~100词）→ 正文触发时加载（理想 <500 行）→ 资源按需（不限量，脚本可以执行而不载入）**。配套两条细则：接近 500 行就再加一层层级并写清“接下来去哪读”；超过 300 行的参考文件要带目录。
还有一个针对多领域的组织模式：`cloud-deploy/` 下 `references/aws.md、gcp.md、azure.md` 各一份，SKILL.md 只负责“选路”，Claude 只读命中的那个文件。**references/ 目录本质上是一个手动实现的检索系统**——你把 RAG 的活儿用目录结构干完了，一分钱向量数据库都没花。
```mermaid
flowchart TD
U[用户消息] --> M{第1层: 元数据
name + description
常驻约100词}
M -- 触发 --> B{第2层: SKILL.md 正文
触发时载入, 目标<500行}
B -- 需要细节 --> R[第3层: references/xx.md
只读命中的领域文件]
B -- 需要执行 --> S[scripts/xx.py
执行但不载入内容]
B -- 需要产物 --> A[assets/ 模板与字体]
```
### 2.6 写作风格一节：那句全场最重要的话
> 如果你发现自己在写 ALWAYS 或 NEVER（全大写），或者用了超级僵硬的结构，那是个黄旗——尽量改成解释原因，让模型理解这件事为什么重要。
它给的替代方案是“theory of mind”（把模型当有心智的人对待）+ 解释 why。理由写得很清楚：今天的模型足够聪明，理解了原因就能举一反三，机械规则只能覆盖写过的那几种情况。这一节直接决定了好 Skill 和差 Skill 的分水岭——**差 Skill 是规则表，好 Skill 是带理由的决策原则**。但同时注意 2.9 节：官方自己也会在极少数地方破例用全大写，这不是双标，是“黄旗”本来就是黄旗而非红线。
### 2.7 测试系统：把 A/B 工程实践搬进 Skill 写作
这是全文工程密度最高的部分，几个关键设计值得逐一抄：
**① with_skill 与 baseline 必须同轮并行。** 每个测试用例同时起两个子代理：一个带着 Skill 跑，一个不带（或带旧版本）跑。原文特意强调“不要先跑带 Skill 的再回来补 baseline，要一次性全部发出”。这是控制变量法在提示词评测里的应用——不同时间跑，模型版本、随机性都会引入偏差。
**② 断言（assertion）延迟起草。** 测试跑起来的空档才去写断言——把流水线的等待时间利用起来。断言要求“客观可验证 + 名字自解释”，且明确划界：写作风格、设计质量这类主观产物不要硬造断言，交给人评。
**③ 数据契约思维。** grading.json 的字段名被钉死为 `text / passed / evidence`，原文特意警告“不要用 name/met/details 之类的变体——**the viewer depends on these exact field names**”。下游渲染脚本依赖精确字段名，这是把前后端契约意识用在了目录里的 JSON 文件上。自己写带脚本资产的 Skill 时，这是必须抄的一条。
**④ 时机敏感数据的即时落盘。** 子代理完成通知里的 `total_tokens` 和 `duration_ms` “只有这一次机会拿到，不会持久化到别处”，要求逐条即时写入 timing.json，不许攒批。这是长流程编排里的通用纪律。
**⑤ 先给人看，再自己改。** 原文全篇唯一一处全大写咆哮留给了这里：*"GENERATE THE EVAL VIEWER **BEFORE** evaluating inputs yourself"*——评审页面必须在 Claude 自己评估之前交到用户手里。理由藏在 Cowork 一节的吐槽里（“不知为什么 Cowork 环境总让 Claude 忘了生成评审页”）：**人是最早、也是最终的质量关口，模型自查不能替代人审**。
### 2.8 Improving 一节：Skill 写作哲学四条
迭代循环里官方给了四条改进心法，每条都值得单独抄录：
1. **从反馈泛化，不要过拟合。** 用户只陪你迭代三五个例子，但 Skill 要被用百万次。针对个例打补丁（"fiddly overfitty changes"）是死路，换个比喻、换种工作模式去解决 stubborn issue 才是活路。
2. **保持精瘦。** 删掉没在产生价值的内容——而且要读 transcript 而不是只看最终输出，如果 Skill 导致模型浪费时间做无用功，删掉肇因部分。
3. **解释 why（对 2.6 的重申与展开）。** 用户反馈哪怕又短又气，也要先真正理解任务，再把这份理解传进指令。
4. **重复三次 = 打包成脚本。** 读测试 transcript，如果三个测试用例的子代理各自独立写了相似的 `create_docx.py`，这就是该把脚本放进 `scripts/` 的强信号。**会话内观察到的重复模式应当沉淀为可复用资产**——这是 Skill 迭代和普通代码重构在心智上最相通的一点。
### 2.9 触发词优化：把一行 description 当模型来训练
全文技术含量最高的一段藏在后面：description 决定触发，而触发可以被量化优化。流程是——
- 造 20 条评测查询，一半 should-trigger、一半 not，**负例必须是“近似误触”**（共享关键词但实际需要别的东西），太容易的负例“什么都测不出来”；
- 正例要求覆盖不同口吻（正式/口语/带错别字/带具体文件路径和公司背景的富细节 query），原文给的反例是 `"Format this data"` 这种抽象话，正例是“我老板发我的那个 'Q4 sales final FINAL v2.xlsx'，C 列收入 D 列成本，帮我加一列利润率百分比”这种真实输入；
- 然后 `run_loop.py` 自动化：**60% 训练 / 40% 留出测试**，当前 description 每条查询跑 3 次统计触发率，再用带扩展思考的 Claude 提改进版，最多迭代 5 轮，**最终用测试集分数而非训练集分数选 best_description，防止过拟合**。
把训练/验证集防过拟合的标准范式用在优化一句 description 上——这段是全文最漂亮的部分。它还在旁边补了一句机制解释：Claude 只在“自己搞不定的复杂任务”上才查 Skill，简单一步任务（"read this PDF"）描述写得再好也不会触发，所以**评测 query 本身必须有足够复杂度**。这解释了很多作者“我的 Skill 描述明明写了怎么不触发”的困惑：不是描述的错，是任务太简单根本不查表。
### 2.10 多环境降级矩阵
文末两大节分别讲 Claude.ai 和 Cowork 环境下怎么降级：没有子代理就“自己逐个跑测试”（明确标注这不如独立子代理严谨，用人审补偿）；没有浏览器就 `--static` 导出 HTML；没有 CLI 就跳过触发词优化。**同一个 Skill 服务多种运行时，靠的是逐能力点声明降级路径，而不是假设一个理想环境。** 你写的 Skill 如果依赖 Bash 或子代理，照抄这个模式能少一半“在别人机器上跑不动”的 Issue。
## 三、五条可照抄的军规
把以上拆解收敛成写自己第一个 Skill 时能直接执行的五条：
| # | 军规 | 出处段落 |
|---|------|---------|
| 1 | description 写“做什么+触发词枚举+兜底从句”，所有 when-to-use 只放这里 | §2.4 |
| 2 | 正文 <500 行，细节进 references/ 按领域拆文件，超 300 行加目录 | §2.5 |
| 3 | 写“原则+原因”，删掉全大写 MUST；破例全大写只留给极少数生死线 | §2.6、§2.7⑤ |
| 4 | Skill 写完必须跑 with/without 对照测试，断言只做客观可验证项 | §2.7 |
| 5 | transcript 里重复出现三次的操作，沉淀为 scripts/ 资产 | §2.8 |
## 四、动手：最短路径写出第一个 Skill
```bash
# 1. 建目录（个人级 Skill 放这里，Claude Code 自动发现）
mkdir -p ~/.claude/skills/my-first-skill/references
# 2. 写最小的 SKILL.md（10 行就能工作）
cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: 帮我写周报。当用户提到周报、weekly report、本周总结、
要向老板汇报进度时使用，即使用户没有明确说"周报"这个词。
---
# 周报生成
## 原则
- 从 git log 和对话中提取本周实际做过的事，不要编造
- 输出三段：本周期成果 / 数据变化 / 下周期计划
- 语气对齐用户所在团队的惯例，先问一句"有固定模板吗"
EOF
# 3. 找市场上同类 Skill 对标
npx skills find weekly-report
```
写完第一步就可用。想走官方完整闭环（测试→基线→评审→触发词优化），安装官方 skill-creator：
```bash
# 从官方仓库取（github.com/anthropics/skills）
git clone https://github.com/anthropics/skills
cp -r skills/skill-creator ~/.claude/skills/
# 或者用 skills CLI 定位市场上的分发版本
npx skills find skill-creator
```
## 五、评测表
（评分为基于 skill-creator 原文全文精读的编辑评测；其随 example-skills 插件分发、由 Anthropic 官方维护，未见独立 Star/下载数据，社区活跃度按官方维护强度评估）
| 维度 | 权重 | 得分 | 依据 |
|------|------|------|------|
| 功能完整度 | 25% | ★★★★★ | 意图捕获→草稿→测试→评审→迭代→触发词优化→打包，唯一覆盖全生命周期的 Skill |
| 设计质量 | 25% | ★★★★★ | 三层渐进披露、数据契约、防过拟合的触发优化，本身就是设计范式展品 |
| 实战效果 | 20% | ★★★★☆ | 闭环有效但重人审：需要用户配合看评审页、给反馈，全自动场景折扣（官方自认盲评“大多数用户用不上”） |
| 上手难度 | 15% | ★★★☆☆ | 零配置安装，但 eval/workspace/iteration 目录体系与断言概念对新手有门槛，原文也因此写了大量口语化补偿 |
| 社区活跃度 | 15% | ★★★★☆ | Anthropic 官方维护、随插件持续分发；作为“母文”被无数社区 Skill 隐式模仿 |
**加权总分：4.6 / 5**
## 六、排行榜：全文最值得抄的五个段落
1. 🥇 **触发词优化 loop**（§2.9）— 训练/留出划分 + 负例近似误触 + 3 次重复测触发率，工程范式级
2. 🥈 **Writing Style 黄旗宣言**（§2.6）— 一句话改变了大多数 Skill 的写法
3. 🥉 **with/baseline 同轮并行**（§2.7①）— 证明 Skill 有效性的最小正确实验设计
4. **description 推式三段式**（§2.4）— 新手见效最快的单点改动
5. **多环境降级矩阵**（§2.10）— 让 Skill 在任何运行时都能给出可用路径
## 参考来源
1. [anthropics/skills 官方仓库](https://github.com/anthropics/skills) — skill-creator 所在的官方 Skills 仓库，本文所有引用片段的出处
2. example-skills 插件本地缓存（本机 `/root/.claude/plugins/cache/anthropic-agent-skills/example-skills/`）— 经会话完整加载核实的 skill-creator 原文
3. [skillsmp.com](https://skillsmp.com) — 2300+ Skills 可搜索目录，用于确认 skill-creator 类元工具的生态分布
4. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — Claude Skills & Agent Skills Library，官方与社区精选收录
5. [skills.sh](https://skills.sh) — 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 等场景全覆盖。
