<!-- title: 写第一个Skill：官方模具逐段拆 -->

**Round 8 · 设计模式提炼**：本期不拆榜单新面孔，拆那件「教你写 Skill 的 Skill」——官方 `skill-creator`。它是生态里唯一一个本职工作就是「生产其他 Skill」的技能：读它一遍，既是学方法论，也是看一份活的写作示范。本文素材为该 Skill 安装副本（本机 `~/.claude/skills/skill-creator/SKILL.md`）的全文逐段精读，全文引文均出自原文；凡未经核实的榜单数字一律不引。

## 一、为什么是它：一份文件，双重身份

先说一个本机观察到的事实：当前环境里同时装着三份 skill-creator——独立版 `skill-creator`、官方示例包里的 `example-skills:skill-creator`、以及 Obsidian 插件内嵌的 `obsidian:skill-creator`。一个技能被三方反复打包内嵌，本身就说明它是事实上的「模具标准件」。

它的正文结构是一条完整的流水线：捕捉意图 → 访谈调研 → 写 SKILL.md 草稿 → 并发跑测试 → 人工评审 → 按反馈迭代 → 描述触发优化 → 打包交付。全文约五百行，正好压在它自己建议的「正文不超过 500 行」红线上——这不是巧合，是自我执行。

更有意思的是它的双重身份：**它教的每一招，它自己都在用；它偶尔破戒的地方，恰恰是最值得学的工程决策**。下面逐段拆。

## 二、骨架：三层渐进披露与目录解剖

skill-creator 给出的标准目录解剖图，值得原样抄走：

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - 可执行脚本，干确定性、重复性的活
    ├── references/ - 按需载入上下文的文档
    └── assets/     - 直接进输出的文件（模板、图标、字体）
```

配套的三级加载机制是整个 Skill 体系的地基：

| 层级 | 内容 | 上下文成本 |
|------|------|-----------|
| 元数据 | name + description | 常驻上下文，约 100 词 |
| 正文 | SKILL.md body | 触发时载入，理想不超过 500 行 |
| 捆绑资源 | scripts/references/assets | 按需加载，无上限；脚本可不载入直接执行 |

原文还给了两条容易被忽略的细则：正文接近 500 行时，**要加层级并写清「下一步去哪读」的指针**；超过 300 行的参考文件要带目录（TOC）。

多域支持有现成的组织范式——按变体拆参考文件：

```
cloud-deploy/
├── SKILL.md (工作流 + 选型)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

原文一句话点破收益：「Claude reads only the relevant reference file.」上下文经济学是 Skill 设计的第一性原理。

## 三、description 官方定调：宁可错触，不可漏触

这是全文信息密度最高的一段。skill-creator 明确指出当前的主要失败模式是 **undertrigger（该触发不触发）**，所以原文要求把描述写得「pushy」一点，并给了对照组：

> instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "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.'**"

三条可执行的硬规则：

1. **「何时用」的全部信息放 description，不放正文**——原文原话：「All 'when to use' info goes here, not in the body.」正文只管「怎么干」。
2. **description 要覆盖用户不会说的那些说法**：仪表盘、数据可视化、内部指标、公司数据……用户嘴里的词和你的功能名往往对不上。
3. **一个冷知识**：原文披露了触发机制的关键细节——「Claude only consults skills for tasks it can't easily handle on its own」。「读一下这个 PDF」这种一步任务，描述写得再好也不会触发，因为模型自己就能干。**Skill 的真实生态位是复杂、多步、专业化的活**。这直接决定了你的触发测试题必须出得足够「重」，轻量题测不出任何东西。

触发优化本身有一条独立的自动流水线：生成 20 条真实触发测试题（一半应触发、一半不应触发），按 60/40 切成训练集和留出集，每题实测 3 次触发率，只针对失败案例改写描述，最多迭代 5 轮，**最终按测试集分数而非训练集分数定稿**——原文的理由写得很直白：「to avoid overfitting」。整套思路就是把机器学习的评估纪律搬到了提示词工程上。

关于负例（不应触发）的测试题，原文有一句精髓：

> the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different.

「写个斐波那契函数」作为 PDF 技能的负例太容易了，测不出任何东西；真正有价值的负例是那些**共享关键词但实际需要别的东西**的擦边题。

## 四、文风戒律：解释为什么，别喊 ALWAYS

skill-creator 的写作观集中在两段。第一段是**黄旗警告**：

> If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why.

背后的假设是：「Today's LLMs are *smart*. They have good theory of mind」——今天的模型有心智理论，给足理由就能举一反三，硬性命令反而制造脆弱。

第二段更有意思：**它自己破戒了**。在 Cowork 环境说明里，因为模型反复忘记生成评审页面，原文写了这样一段：

> Sorry in advance but I'm gonna go all caps here: **GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself.**

官方模具在自己的文本里全大写喊话，还附带道歉。这不是打脸，而是这条戒律的正确用法：**「解释为什么」是默认档位；当某个指令被实测反复跳过时，升级为强制语气的成本收益才转正**。戒律是统计规律，不是教条——这正是「实测驱动」的提示词工程和「背诵教条」的分水岭。

顺带一提它的口吻：「Cool? Cool.」「this is pretty important (we are trying to create billions a year in economic value here!)」——技能的读者是模型，口吻完全可以像同事聊天，不必装成法律文书。

## 五、真正的护城河：评测闭环

绝大多数第三方 SKILL.md 止步于「写好指令」，skill-creator 用一半篇幅讲的是**写完之后怎么证明它好**。这套机器有几个值得逐个抄的设计：

**1. 带技能 vs 基线，同回合并发。** 每条测试题派两个子代理——一个带技能、一个不带（改进存量技能时，基线改为旧版快照）。原文特别强调必须同一回合全部发出，不要跑完实验组再补对照组——保证所有运行差不多同时结束，评审不被阻塞。

**2. 时序数据的即时捕获。** 每个子代理完成时的 token 数和耗时只存在于任务通知里，原文原话：「This is the only opportunity to capture this data」——错过通知，数据就没了。所以指令要求逐条到达逐条落盘 `timing.json`，不许攒批。

**3. 字段名即 API 契约。** 评分文件 grading.json 的断言数组必须用 `text`、`passed`、`evidence` 三个字段，原文特意警告不要写成 name/met/details 之类的变体——「the viewer depends on these exact field names」。**多个技能文件之间的协作靠的是字段级契约**，这是把 SKILL.md 当 API 写的最直接证据。

**4. 分析师遍。** 聚合出基准表（通过率、耗时、token 用量，均值±标准差和差值）之后，还要专门做一轮分析，找三类聚合数字会掩盖的问题：**无论带不带技能都通过的「无区分度断言」、高方差的「可疑抖动用例」、时间与 token 的取舍点**。评测不是跑个分就完，分数要被审问。

**5. 断言的适用边界。** 原文明确：客观可验证的输出（文件转换、数据抽取）才配断言；主观输出（文风、设计感）别硬造断言，交给人评。「Good assertions are objectively verifiable and have descriptive names.」

**6. 评测同时是防过拟合装置。** 改进环节的方法论原文说得极重：

> we're trying to create skills that can be used a million times … **if the skill you and the user are codeveloping works only for those examples, it's useless.**

具体的操作化建议有三条，条条能直接搬走：
- 从反馈里**泛化**，不做小修小补（overfitty）的改动；遇到顽固问题，换比喻、换工作模式，而不是加更多限制；
- **保持精简**：去读测试运行的完整轨迹而不只看最终产物，发现模型在某个环节空转，就把导致空转的指令删掉；
- **重复劳动信号**：如果三条测试里子代理不约而同都自己写了一个 `create_docx.py`，这就是把该脚本固化进 `scripts/` 的强信号——「Write it once, put it in scripts/, and tell the skill to use it.」

整条评测闭环如下图：

```mermaid
flowchart TD
    A["捕捉意图：四问定边界"] --> B["访谈补齐边界用例"]
    B --> C["写 SKILL.md 草稿"]
    C --> D["拟 2 到 3 条真实测试题"]
    D --> E["同一回合并发两组运行"]
    E --> F["带技能运行"]
    E --> G["基线运行"]
    F --> H["等待期先写断言"]
    G --> H
    H --> I["逐项判分落盘"]
    I --> J["聚合成基准表"]
    J --> K["生成评审页交给人"]
    K --> L["读反馈文件"]
    L --> M{"反馈是否全空"}
    M -->|全为空| N["打包交付"]
    M -->|有具体抱怨| O["从单例泛化出修改"]
    O --> E
```

描述触发优化是第二条独立的环：

```mermaid
flowchart LR
    A["生成 20 条触发测试题"] --> B["六成训练四成留出"]
    B --> C["每题三次实测触发率"]
    C --> D["只针对失败案例改描述"]
    D --> E{"未满五轮且仍有改进"}
    E -->|是| C
    E -->|否| F["按测试集分数定稿"]
```

## 六、人的部分：沟通校准与安全边界

skill-creator 里有一段在所有技能里都罕见的指令——**校准对人类的说话方式**：

> there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm".

所以它规定：「JSON」「assertion」这类术语，必须先看到用户懂行的明确信号才能裸用；拿不准就先给一句定义。这揭示了一个常被忽略的事实：**造技能的过程是半人机协作流程，技能文本里可以、也应该包含「如何对待眼前这个人」的指令**。

安全侧只有短短一段，名为「Principle of Lack of Surprise（无意外原则）」：技能不得包含恶意代码或任何「与描述不符会让人吃惊」的内容，并明确拒绝制造误导性技能、未授权访问或数据外泄工具。同时留了口子：「roleplay as an XYZ」这类角色扮演没问题。边界画得干净：**意外性本身是恶意软件的特征，而不是某个具体功能**。

还有一条运维细节值得记：更新存量技能时「Preserve the original name.」——目录名和 frontmatter 的 name 字段原样保留，输出 `research-helper.skill` 而不是 `research-helper-v2`；安装路径可能只读，先拷到可写位置再改。命名稳定性是分发生态的契约。

## 七、照着写：你的第一个最小可行 Skill

把官方方法论压缩成五步：

1. **四问定边界**：做什么？何时触发（用户会说什么话）？输出格式？产出可客观验证吗（可验证才配测试题）？
2. **建目录**：`mkdir -p ~/.claude/skills/<名字>/`，先只写 SKILL.md，别急着堆资源。
3. **写 frontmatter**：name + 一条 pushy 的 description（何时用 + 是什么 + 边界说法全塞进来），正文控制在百行级起步，每条指令解释为什么。
4. **配 2-3 条真实测试题**：像真用户会说的话，带具体路径、文件名、背景细节。原文给的反例是「Format this data」这种空话，正例是「boss 发来 Q4 sales final FINAL v2.xlsx，想加一列利润率百分比，收入在 C 列成本在 D 列」这种带着生活噪音的题。
5. **跑 with/without 对比**，看差异、读轨迹、从单例泛化出修改，再跑一轮。

按这套纪律写出的最小模板长这样（本文按官方方法论拟的示例，非官方文件）：

```markdown
---
name: meeting-notes-cleaner
description: 把杂乱的会议速记整理成结构化纪要。只要用户贴入未整理的会议记录、
  语音转写或群聊文字，即使没说「整理纪要」也要使用本技能。
  固定输出：结论在前、待办带负责人与期限、争议点单列。
---

# 会议纪要整理

## 为什么这样整理
速记的价值在会后五分钟内可被追责，所以结论必须前置，
待办必须落到人头上——无法确认的负责人一律标「待确认」，不要编造。

## 输出模板
（固定结构写在这里）

## 边界
- 原文含糊处保留原话并标注，不做美化
```

安装官方模具本体的命令：

```bash
# 从官方仓库装到个人技能目录
git clone --depth 1 https://github.com/anthropics/skills /tmp/anthropics-skills
find /tmp/anthropics-skills -type d -name skill-creator
cp -r <find 结果中的 skill-creator 目录> ~/.claude/skills/

# 或用生态目录 CLI 定位
npx skills find skill-creator
```

装好后直接说「帮我把刚才这套流程做成一个 skill」，它就会接管全流程。验收自查清单：description 够不够 pushy？「何时用」是否全在 description？每条指令有没有给理由？有没有至少两条带生活噪音的真实测试题？有没有跑过不带技能的基线？

## 八、评分与排行

| 维度 | 权重 | 评分 | 依据 |
|------|------|------|------|
| 功能完整度 | 25% | ★★★★★ | 从起草、测试、评审、迭代到触发优化、打包的全链路闭环，罕见地覆盖了「写完之后」 |
| 设计质量 | 25% | ★★★★★ | 三层披露、字段级 API 契约、防过拟合纪律，官方最佳实践的原产地 |
| 实战效果 | 20% | ★★★★☆ | 评测闭环确实能收敛质量，但每轮双倍子代理的成本不低，轻量用户跑不动全程 |
| 上手难度 | 15% | ★★★☆☆ | 用它造技能很顺；读懂整套 eval 机器需要工程背景——它自己都为此写了术语校准段 |
| 社区活跃度 | 15% | ★★★★☆ | 官方出品，内置 Claude.ai / Claude Code / Cowork 三平台分支说明，可见随平台演进维护；本环境三方内嵌即旁证。具体 star 数未核实，不列 |

**加权总分约 4.4 / 5。**

**最值得抄进你自己 SKILL.md 的五处设计**（按性价比排序）：
1. pushy description——把「何时用」全部塞进 description，覆盖用户不会说的那些词；
2. explain-why 文风——用理由替代全大写命令，全大写只留给实测反复失败的那一条；
3. 三层渐进披露骨架——正文守 500 行红线，超长参考带目录，多域按变体拆文件；
4. with/without 基线——没有对照组，你无法区分「技能的贡献」和「模型本来就会」；
5. 重复劳动信号——测试里子代理不约而同手写的脚本，就是该进 `scripts/` 的脚本。

**三处别照抄**：满篇口语插话（「Cool? Cool.」）是元技能的特权，生产技能别模仿；全套评测机器对一次性小技能是杀鸡用牛刀，两条测试题足矣；平台专属分支（Claude.ai/Cowork）只有当你真的跨平台分发时才需要。

## 结论

这一轮拆下来，最大的发现不是任何单条技巧，而是重心的迁移：**Skill 写作的门槛在 frontmatter，天花板在评测闭环**。description 决定它活不活得下来（触发），评测决定它长不长得高（质量收敛）。skill-creator 用自己五百行的正文示范了一件事——写技能正在从「写提示词」变成「建评估」：对照组、断言、基准表、留出集、防过拟合，这套词汇表就是下一代技能作者的必修课。你的第一个 Skill 不必从这套重装备起步，但应该从第一天就知道终点在哪。

## 参考来源

1. [Skill Creator — SKILL.md 全文](https://github.com/anthropics/skills) — 本文全部引文与拆解对象，本机安装副本位于 `~/.claude/skills/skill-creator/SKILL.md`，上游为官方 anthropics/skills 仓库
2. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，skill-creator 与官方示例件（docx/pptx/pdf 等）的发布地
3. [skillsmp.com](https://skillsmp.com) — Skills 聚合目录，可用于核对本机三份 skill-creator 副本对应的各分发渠道（本期未抓取榜单数据）

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)