<!-- title: 官方skill-creator逐文件拆解 -->

# 官方 skill-creator 逐文件拆解：教你造 Skill 的那个 Skill

## 概述

本期是 Skills 生态拆解第 2 轮，主题是单 Skill 深度拆解。对象选了生态里最特殊的一个：`anthropics/skills` 官方仓库的 **skill-creator**——官方管它叫“创建有效 Skills 的指南”，说白了就是“造 Skill 的 Skill"。选它有三个理由：其一，它是有史以来被“引用”最多的 Skill——生态里每一篇教人写 SKILL.md 的教程，底层逻辑几乎都出自它的正文；其二，它是官方设计哲学的“自举样本”——它教导的所有规范（渐进式披露、资源分层、反面清单），全部在它自己的目录结构里落地执行，等于官方亲手写的标准答案；其三，它自带 `init_skill.py`/`package_skill.py` 脚手架和 eval-viewer 评测工具，是目前把“Skill 工程”做成完整工具链的唯一公开范本。本文数据全部来自 2026-08-28 对 skills.sh 实时榜单、anthropics/skills 仓库页面与 SKILL.md 原文的真实抓取，逐文件拆到段落级。

## 一、为什么拆它：安装量不高、影响力最大的官方元技能

先看它今天在榜上的位置——这本身就是个反差信号。2026-08-28 抓取的 skills.sh 全时安装榜上，前 101 名里**没有出现 skill-creator**：榜单第 101 名 azure-quotas 的安装量约 40.2 万，而 skill-creator 低于这个量级。对照头部：find-skills（vercel-labs/skills）300 万断层第一，grill-me（mattpocock/skills）91.1 万第二，同仓的官方 frontend-design 79.67 万第三。

一个“教所有人写 Skill”的官方元技能，安装量却进不了前 100。原因不难理解：**它是作者型 Skill，不是用户型 Skill**。装它的人是想造 Skill 的开发者，基数天然小；但它的影响通过“被造出来的 Skill”二次放大——生态里数百万份 SKILL.md 的结构（frontmatter 两字段、三类资源目录、渐进式披露），源头都是这份文档。看仓库盘子就知道了：anthropics/skills 今日页面实抓 **Star 约 17 万、Fork 2.02 万、开放 Issue 314 个、开放 PR 790 个**，是整个 Agent Skills 生态最大的单一仓库。

顺带修正一个常见误解：官方 README 明确说明，仓库里 `skills/docx`、`skills/pdf`、`skills/pptx`、`skills/xlsx` 四个文档技能是 **source-available 而非开源**，其余示例技能（含 skill-creator）为 Apache 2.0；skill-creator 的 frontmatter 里 `license: Complete terms in LICENSE.txt` 指向的正是这套授权安排。

## 二、评测对比表

把 skill-creator 和前几轮深拆过的两个头部样本做一次“设计哲学对照”（评分口径：五星制，上手难度星级越高越容易）：

| 维度 | 权重 | skill-creator（anthropics） | grill-me（mattpocock） | frontend-design（anthropics） |
|------|------|------------------------------|------------------------|-------------------------------|
| 功能完整度 | 25% | ★★★★★ 从脚手架、打包到评测全链路 | ★★★★☆ 单一质询场景做到极致 | ★★★★☆ 只管生成侧 |
| 设计质量 | 25% | ★★★★★ 官方规范的"自举实现" | ★★★★★ 一行正文的薄壳艺术 | ★★★★★ 负样本校准教科书 |
| 实战效果 | 20% | ★★★★☆ 产出质量取决于使用者访谈质量 | ★★★★★ 效果直接可感 | ★★★★☆ 去AI味反馈明显 |
| 上手难度 | 15% | ★★★☆☆ 需理解六步流程和资源分层 | ★★★★★ 零门槛 | ★★★★★ 零配置 |
| 社区活跃度 | 15% | ★★★★★ 官方仓库持续迭代（314 开放 Issue） | ★★★★★ 91万安装 | ★★★★★ 79.7万安装 |
| **加权综合** | | **4.7** | **4.8** | **4.6** |

三者其实是三种物种：grill-me 是“极薄壳”（正文一行，靠提问引擎干活），frontend-design 是“纯提示词”（两个文件，全靠领域判断力），skill-creator 是“全家桶”（SKILL.md + 脚本 + 参考 + 评测工具的完整工程）。拆完你会明白：**没有最优的 Skill 形态，只有和任务脆弱度匹配的形态**——这句话正是 skill-creator 自己的核心教义。

## 三、目录结构：官方自己“吃狗粮”的全家桶

GitHub 目录列表（2026-08-28 实抓）显示，`skills/skill-creator/` 下有这些东西：

```
skill-creator/
├── SKILL.md          # 主文档（约300行）
├── LICENSE.txt       # 授权条款
├── references/       # 参考文档（workflows.md、output-patterns.md）
├── scripts/          # 脚手架与打包脚本（init_skill.py、package_skill.py）
├── assets/           # 输出资源
├── agents/           # 子代理配置
└── eval-viewer/      # 评测结果可视化工具
```

对照它自己在 SKILL.md 里画的“标准 Skill 解剖图"（SKILL.md + scripts/ + references/ + assets/），你会发现官方给自己的产品**超额交付**了两个目录：`agents/` 和 `eval-viewer/`。这两个“超纲”目录暴露了官方的真实野心——Skill 不只是提示词包，而是一个带脚手架、带打包器、带评测台的小型软件工程。上一轮拆的 frontend-design 全仓只有两个文件，这一轮的 skill-creator 是另一个极端，两者放在一起，恰好是这个生态形态光谱的两个端点。

## 四、SKILL.md 逐段拆解

### 4.1 frontmatter：description 里藏着 update 场景

```yaml
name: skill-creator
description: Guide for creating effective skills. This skill should be used
  when users want to create a new skill (or update an existing skill) that
  extends Claude's capabilities with specialized knowledge, workflows, or
  tool integrations.
license: Complete terms in LICENSE.txt
```

拆开看，这段 description 是标准的官方三段式：**是什么**（Guide for creating effective skills）→ **何时触发**（when users want to create…）→ **价值抽象**（specialized knowledge, workflows, or tool integrations）。最容易被忽略的细节是括号里的 `(or update an existing skill)`——它把“改造旧 Skill”也纳入了触发范围。官方教程反复强调“触发信息全部写在 description，不要指望正文”，因为正文只有触发之后才会加载；这句括号就是最佳实践：**触发词要覆盖任务的全生命周期，而不只是第一次**。另外注意 frontmatter 只有 name、description、license 三个字段——SKILL.md 明文警告"Do not include any other fields"，别自作聪明加 author、version，宿主不认。

### 4.2 About Skills：一句"入职指南"定位全场

正文开篇给 Skill 下了个定义："**Think of them as 'onboarding guides' for specific domains or tasks**"——把它们想成特定领域的“新员工入职指南”，把通用 Agent 变成装备了程序性知识的专业 Agent。这个比喻是全篇的锚点：入职指南写给谁？写给已经很强的新员工——这就是下一节“Claude 已经很聪明”公理的伏笔。随后列出 Skill 提供的四类价值：专业工作流、工具集成、领域知识（公司 schema、业务逻辑）、捆绑资源。写自己 Skill 时，这四类正好可以当需求检查表：你的 Skill 属于哪一类？如果一类都靠不上，它大概率不该存在。

### 4.3 Concise is Key：把上下文窗口当公共财

这是全篇第一个“设计公理”：

> **The context window is a public good.**（上下文窗口是公共财。）

SKILL.md、系统提示、对话历史、其他 Skill 的元数据、用户的实际问题——全部挤在同一个窗口里，任何 Skill 的冗长都是在侵犯公共用地。由此推出两条操作性极强的写作纪律：

- **默认假设：Claude 已经非常聪明**。只写模型不知道的东西，每段话都要过一遍审计：“Claude 真的需要这段解释吗？这段话配得上它的 token 成本吗？"
- **用紧凑的例子替代冗长的解释**。

这个“token 成本审计”句式值得所有作者直接抄走——它把“写短点”这种空洞建议变成了可执行的自检动作。

### 4.4 自由度三档制：窄桥与田野

第二节设计公理叫 **Set Appropriate Degrees of Freedom**，按任务的脆弱性和可变性分三档：

| 自由度 | 形式 | 适用场景 |
|--------|------|---------|
| 高 | 文字指令 | 多种做法都成立、靠启发式判断 |
| 中 | 带参数的伪代码/脚本 | 存在偏好模式、允许变化 |
| 低 | 参数极少的固定脚本 | 操作脆弱易错、一致性生死攸关、步骤顺序不可乱 |

配套的比喻极其传神："**把 Claude 想成在探路：悬崖边的窄桥需要具体护栏（低自由度），开阔田野可以随便走（高自由度）**"。这解决了一个新手最常见的错误——要么全写成死板步骤把模型框死，要么全写成宽泛建议让结果不可复现。写 SKILL.md 前，先给每个环节标注“这是窄桥还是田野”。

### 4.5 Anatomy：三类资源的“何时该带”

官方解剖学给三类可选资源各配了一张“携带清单"：

- **scripts/**：同一代码被反复重写、或需要确定性可靠性时才写脚本，例：`rotate_pdf.py`。最大好处是“可以不读入上下文直接执行”——这是唯一不占 token 窗口的资源形态。
- **references/**：工作时按需查阅的文档，如 schema、API 文档、公司政策。纪律很硬：**信息只能活在一个地方**（SKILL.md 或 references，不许两边重复）；文件超 1 万词就要在 SKILL.md 里给 grep 检索模式。
- **assets/**：不进上下文、直接进产出的文件——模板、字体、logo、前端样板。和 references 的本质区别是“读它”还是“用它”。

### 4.6 反面清单：一个 Skill 不该有什么

全篇最反直觉的一节。官方明令禁止在 Skill 里创建 README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md 等任何“人类向”辅助文档，理由一句话：

> **Skill 的读者是 AI，不是人。**

人类开源习惯里的“礼貌性文件”（README、CHANGELOG）在 Skill 语境里全是污染上下文的噪音。这个反面清单模式（列 explicitly 不要做什么）比正面清单更能纠正模型行为，前几轮拆过的 frontend-design 反AI俗套清单、azure-deploy 前置门禁，用的都是同一家族的手法——**用“负面样本”划边界，比用“正面描述”画圈更省 token 也更抗跑偏**。

### 4.7 渐进式披露：三级加载与三条护栏

这是 skill-creator 被引用最多的部分，Skill 生态的“宪法条款”：

1. **元数据**（name + description）：约 100 词，常驻上下文——这是唯一的触发面；
2. **SKILL.md 正文**：触发后加载，建议 5000 词以内、**500 行红线**；
3. **捆绑资源**：按需加载，量级不设限——因为脚本可以执行而无需读取。

正文里给了三种拆分模式：高级指南 + references 链接（PDF 处理例）、按领域拆文件（BigQuery 的 finance/sales/product 各一个 md，用户问销售只读 sales.md）、按条件拆（DOCX 编辑里“简单改动 XML，要红线批注才去读 REDLINING.md"）。外加两条硬护栏：**references 只允许一层深**（不许 A 引 B、B 再引 C 的套娃）；**超 100 行的参考文件顶部必须有目录**，让模型预览时就能看到全貌。

### 4.8 六步创建流程：访谈、worked examples、打包即验证

正文最后三分之一是完整工作流，六步顺序执行：

```mermaid
flowchart LR
    A["1 理解<br/>拿具体例子访谈"] --> B["2 规划<br/>列出可复用资源"]
    B --> C["3 初始化<br/>init_skill.py"]
    C --> D["4 编辑<br/>实现资源+写SKILL.md"]
    D --> E["5 打包<br/>package_skill.py<br/>先校验后打包"]
    E --> F["6 迭代<br/>真实使用中改进"]
    F -.->|反馈| D
```

几个值得逐个品的设计：

- **Step 1 是访谈式需求收集**。官方示范的提问包括“这个 Skill 该支持哪些功能？给我几个使用例子？**用户会说什么话来触发它？**"——最后这个问题直指触发词设计的本质：description 不是功能描述，是用户话语到 Skill 的映射表。
- **Step 2 用三个 worked examples 精确对齐三类资源**：pdf-editor 需要反复写旋转代码 → 收进 `scripts/`；frontend-webapp-builder 需要同样的 HTML/React 样板 → 收进 `assets/hello-world/`；big-query 每次都要重新发现表结构 → 收进 `references/schema.md`。三个例子、三种资源、一一对应——这是“紧凑例子优于冗长解释”教义的自我示范。
- **Step 4 的视角转换**："**记住这个 Skill 是写给另一个 Claude 实例用的**"——作者要问的不是“我想说什么”，而是“另一个 Claude 在执行时有什么非显而易见的知识缺口”。
- **Step 5 打包即校验**：`package_skill.py` 先验证 frontmatter、命名规范、描述完整性，全部通过才产出 `.skill` 文件（本质是 zip 改后缀）；验证不过直接退出，不给带病发布的机会。
- **Step 6 迭代闭环**：在真实任务里用 → 观察卡点 → 回改 SKILL.md → 再测。

## 五、资源目录：references、scripts 与 eval-viewer

SKILL.md 正文里明确点名了两个参考文件：`references/workflows.md`（多步流程与条件逻辑的设计模式）和 `references/output-patterns.md`（输出格式与质量标准的模板模式）——注意引用写法：正文只给一句话摘要 + 何时该读，细节全在文件里，这正是它自己教导的 Pattern 1。脚本侧，`scripts/init_skill.py` 一键生成带 TODO 占位的标准目录（SKILL.md 模板 + scripts/references/assets 三个示例目录），`scripts/package_skill.py` 负责校验加打包。

最有想象空间的是目录列表里的 `eval-viewer/`——官方把“触发词要跑评测”这件事做成了可视化工具。结合官方教程里“用正/负样本测召回率和精确率”的玩法，意味着 skill-creator 实际上是官方唯一开放了**评测基建**的 Skill：写完不是凭感觉觉得“应该会触发”，而是拿样本集跑一遍看数据。这是社区 Skill 目前普遍缺失的一环，也是“Skill 工程”和“提示词手艺”的分水岭。`agents/` 目录则说明它在往子代理协作方向演进，此处不展开（本次未抓取其内容，不作臆测）。

## 六、适用与不适用场景

**适合用它的场景**：团队要沉淀多个内部 Skill（一次学会、批量复用脚手架）；要分发 `.skill` 包给非工程同事（package 的校验流程兜底）；对触发准确率有要求的严肃场景（eval-viewer 提供数据反馈）；想学习 Skill 设计规范本身（它的正文就是官方设计文档）。

**不适合的场景**：只想微调一段固定提示词——六步流程是杀鸡用牛刀，直接写 SKILL.md 更快；一次性任务不值得固化成 Skill（官方 Step 1 的隐含前提是“这些工作流会被反复执行”）；对上下文预算极度敏感的轻量 Agent——skill-creator 自身全家桶的维护成本要认清，它常驻的 description 虽然只有 100 词，但触发后的 500 行正文不算便宜。

## 七、可直接抄走的五个写法模式

1. **反面清单模式**：像 4.6 那样显式列出“不要创建 README/CHANGELOG"，负面边界比正面描述更抗跑偏。
2. **token 成本审计句式**：给每段话配一句“这段配得上它的 token 成本吗”，让精简从美德变成可执行动作。
3. **自由度三档制**：动笔前给每个环节标注窄桥（脚本化）还是田野（文字指引），形式跟随脆弱度。
4. **worked example 对齐资源类型**：用三个具体用例反推 scripts/references/assets 各自该装什么，而不是先搭目录再找内容塞。
5. **“写给另一个 Claude”视角**：全文用祈使句、触发信息全进 description、参考文件一层深、长文件带目录——每一条都是这个视角推出来的必然结论。

## 八、安装与使用

```bash
# 方式一：注册官方插件市场后安装 example-skills 插件（含 skill-creator）
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

# 方式二：npx skills CLI（支持 Claude Code、Cursor、Codex 等 20 个 Agent 宿主）
npx skills add anthropics/skills
```

装好后直接对 Claude Code 说“用 skill-creator 帮我创建一个 XXX 的 Skill"，它会按六步流程先访谈、再生成。GitHub 页面另有 `.skill` 包的下载入口，仓库同时提供 `./spec`（Agent Skills 规范）和 `./template`（最小模板），想看裸骨架的直接看 template。

## 九、推荐排行榜

- **学习 SKILL.md 写法首选**：skill-creator（官方规范原文，没有之一）
- **工程化完整度**：skill-creator > hyperframes（路由式矩阵）> azure-deploy（门禁式）
- **触发评测基建**：skill-creator（eval-viewer）几乎孤本
- **低门槛入门造 Skill**：直接抄 template 最小模板，或用 skill-creator 的 Step 1-2 思路手写
- **综合推荐**：4.7 / 5——它不一定是你装得最频繁的 Skill，但大概率是影响你最深远的一个。

## 参考来源

1. [skill-creator SKILL.md 原文](https://raw.githubusercontent.com/anthropics/skills/main/skill-creator/SKILL.md) — 本文逐段拆解对象，frontmatter、六步流程、渐进式披露条款均出自此文件（2026-08-28 抓取）。
2. [anthropics/skills 仓库 skill-creator 目录](https://github.com/anthropics/skills/tree/main/skills/skill-creator) — 目录结构（references/scripts/assets/agents/eval-viewer）与仓库 Star/Fork/Issue/PR 数据来源。
3. [anthropics/skills 仓库主页](https://github.com/anthropics/skills) — source-available 授权说明、插件市场安装命令、./spec 与 ./template 说明。
4. [skills.sh 榜单](https://skills.sh) — 全时安装榜 Top101 数据、npx skills CLI 与 20 个 Agent 宿主支持列表（2026-08-28 实抓）。

> [!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)