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 原文（经本会话完整加载核实），未核实的数据一律不写。
之前拆过的元工具（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 教程的根本分歧——后者教你格式，它教你闭环。
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 文件]
正文第一段用六行把整个流程讲完，然后才展开细节。这符合官方自己推的渐进披露原则：模型（和人）先要一张地图，才知道当前这段指令处在流程哪个位置。
更有意思的是流程讲完后的那句口语："Cool? Cool."。看似闲笔，实则是刻意的语气设计。skill-creator 后文明确警告不要写满 "musty MUSTs"（发霉的 MUST），通篇用商量式口吻代替命令式——"you can do that instead"、"the order is flexible"。对模型来说，命令式长文容易诱发机械执行，而对话式语气让模型保持对真实语境的判断力。语气本身就是提示词工程的一部分，这是它教的第一课。
它专辟一节讲“怎么跟用户说话”，并给了具体标尺：“evaluation 和 benchmark 边缘可接受；JSON、assertion 这类词，要先看到用户懂行的信号再用”。还配了一段时代观察——水管工开始打开终端、爷爷奶奶开始搜“怎么装 npm”。
这解决的是 Skill 的一个真实痛点：同一个 Skill 会被完全不同水平的人触发。写死一种说话风格必然劝退一半用户。给模型一条“看语境线索调行话密度”的元规则，比枚举用户画像便宜得多。
第一步不是问用户，而是：如果当前对话里已经存在一个用户想固化的工作流（比如用户说“把这个流程做成 skill”），先从对话历史里提取——用了哪些工具、什么步骤顺序、用户纠正过什么、输入输出格式长什么样。提取完再让用户补缺口、确认。
这是很多新手写 Skill 时完全想不到的一层：Skill 的输入不只有用户的这句话，还有整个会话的上下文。会话史里藏着最真实的“用户到底要什么”，比重新访谈准确。
在“写 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 词），正文触发时才加载，放错位置等于永远不被读到。
官方给出的标准目录结构与加载模型：
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 的活儿用目录结构干完了，一分钱向量数据库都没花。
flowchart TD
U[用户消息] --> M{第1层: 元数据<br/>name + description<br/>常驻约100词}
M -- 触发 --> B{第2层: SKILL.md 正文<br/>触发时载入, 目标<500行}
B -- 需要细节 --> R[第3层: references/xx.md<br/>只读命中的领域文件]
B -- 需要执行 --> S[scripts/xx.py<br/>执行但不载入内容]
B -- 需要产物 --> A[assets/ 模板与字体]
如果你发现自己在写 ALWAYS 或 NEVER（全大写），或者用了超级僵硬的结构，那是个黄旗——尽量改成解释原因，让模型理解这件事为什么重要。
它给的替代方案是“theory of mind”（把模型当有心智的人对待）+ 解释 why。理由写得很清楚：今天的模型足够聪明，理解了原因就能举一反三，机械规则只能覆盖写过的那几种情况。这一节直接决定了好 Skill 和差 Skill 的分水岭——差 Skill 是规则表，好 Skill 是带理由的决策原则。但同时注意 2.9 节：官方自己也会在极少数地方破例用全大写，这不是双标，是“黄旗”本来就是黄旗而非红线。
这是全文工程密度最高的部分，几个关键设计值得逐一抄：
① 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 忘了生成评审页”）：人是最早、也是最终的质量关口，模型自查不能替代人审。
迭代循环里官方给了四条改进心法，每条都值得单独抄录：
create_docx.py，这就是该把脚本放进 scripts/ 的强信号。会话内观察到的重复模式应当沉淀为可复用资产——这是 Skill 迭代和普通代码重构在心智上最相通的一点。全文技术含量最高的一段藏在后面：description 决定触发，而触发可以被量化优化。流程是——
"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 描述明明写了怎么不触发”的困惑：不是描述的错，是任务太简单根本不查表。
文末两大节分别讲 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 |
# 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：
# 从官方仓库取（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
/root/.claude/plugins/cache/anthropic-agent-skills/example-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 等场景全覆盖。