概述

第8轮，按系列规划做「设计模式提炼」：不讲某一个 Skill 的功能，而是回答一个问题——一份合格的 SKILL.md 到底是怎么被设计出来的。本期做一个此前七轮都没人做过的动作：放弃榜单视角，把标本库换成一台真实工作机上实装的技能快照——本会话可见的技能清单约四百条，含官方出厂件、内置 harness 技能、双命名空间插件和大量社区件，这是一份任何聚合站都爬不到的「真实安装横截面」。从这份快照和内置技能的描述原文出发，本文提炼出八条可复用的 SKILL.md 写作模式，最后手把手带读者写出并验证第一个自己的 Skill。

一、标本库：榜单给不了的真实横截面

榜单看的是热度，快照看的是留存。一个技能被真正装进日常工作机并留下，本身就是比 Star 更硬的信号。先清点这份快照的构成：

这张表本身就是生态的第一课：命名即分类。作者群体不约而同用后缀表达「我是哪一族」，而撞名与变体泛滥则是无治理的代价——这两点后文都会变成模式。

mindmap
  root((本机实装技能快照))
    角色模仿系
      历史人物 libai luxun
      影视角色 conan zhouxingchi
      名人风格 leijun wangfeng
    官方出厂件
      example-skills 命名空间十六件
      内置 harness 技能
    内容产线
      采集 youtube-transcript
      转制 book-to-short-videos
      发布 twitter-publisher
    开发闭环
      审查 code-review
      验证 verify
      部署四件
    垂直纵深
      电信 3gpp与pcap
      笔记 obsidian与notion
      课程 course-video-maker族

二、核心论点：写 SKILL.md 就是在设计一个 API

把 SKILL.md 和 API 设计对照，几乎每一层都能对上：

这个视角不是比喻游戏——内置技能的 description 原文就是最好的实证。以下引文全部来自本会话可见的内置技能描述：

例一：claude-api，路由正反例双清单。 它的描述里明确写着 TRIGGER when（用户代码 import 了 anthropic SDK、询问 prompt caching 等场景）和 SKIP when（代码 import 的是 openai 或其他厂商 SDK、厂商中立代码）。这就是 API 文档里的「适用输入」与「应拒绝的输入」，写在签名旁边，让路由器第一毫秒就能分流。

例二：code-review，参数语义写进签名。 「Review the current diff for correctness bugs... at the given effort level (low/medium: fewer, high-confidence findings; high→max: broader coverage...)」——一个 effort level 参数的三档语义直接写进描述，还附带 --comment、--fix 两个类 CLI 旗标的副作用说明。用户不需要读正文就知道调这个技能「要花多少上下文、会动不动工作区」。

例三：deep-research，调用前置条件。 描述开头写着 BEFORE invoking 就应检查问题是否足够具体，不够就先问 2-3 个澄清问题。这是 API 设计里的 precondition：与其让调用失败后再补救，不如把检查写进接口约定。

例四：fewer-permission-prompts，句子化命名。 name 本身就是一个完整的动宾句（「减少权限弹窗」），用户看到名字即知功能。对比快照里大量的 xxx-skill 人名后缀，这是两个时代的命名法。

三、八大设计模式

以下每条按「问题 → 模式 → 实证 → 要点」展开。

P1 签名前置：description 是路由表，不是广告词。 问题：多数技能不被触发，是因为 description 只写了「我能做什么」，没写「何时该调我」。模式：把触发场景、输入特征、明确的不适用情形压进 description。实证：claude-api 与 update-config 都带 TRIGGER/SKIP 双清单；update-config 甚至把用户可能说出的原话（「from now on when X」「whenever X」）直接枚举进描述——这是在给路由器喂正则样本。要点：写完 description 自问一句「用户随手说哪句话时应该命中我」，把那句话写进去。

P2 薄入口厚附件：正文是决策路径，不是知识库。 问题：正文越长，每次加载的上下文税越重，且大半内容对本次任务无用。模式：SKILL.md 只留「遇到什么情况→走哪条路」，细节下沉到 references/ 按需加载，可执行逻辑下沉到 scripts/。（官方 pdf 件的分层结构此前已被本系列单独拆过，此处只收为模式族成员，不再重复其内部结构。）要点：经验判断式——单文件超过一屏就该问自己「这一段是不是 references 的一节」。

P3 确定性外置：能写成脚本的不写散文。 问题：让模型用自然语言描述如何格式转换、如何校验，等于把确定性任务交给概率引擎。模式：固定流程固化为脚本，SKILL.md 只负责指挥何时调用、如何解读输出。实证：官方 webapp-testing 用脚本驱动浏览器而非让模型「想象」页面行为；快照里 pcap 三件套（analyzer/generator/modifier）整个族都是围绕二进制格式解析的工具化封装。要点：散文负责「判断」，脚本负责「执行」。

P4 句子化命名：name 从标签进化为动作。 问题：data-tools 这类名词标签让用户和路由器都要猜功能。模式：name 直接写成动宾短语。实证：fewer-permission-prompts、planning-with-files、remembering-conversations、security-ownership-map——快照里官方系命名几乎清一色动作句，而社区系仍是 xxx-skill 人名后缀的海洋。要点：名字里带动词，是判断一个技能「为任务而生」还是「为角色而生」的速测法。

P5 命名空间隔离：plugin:skill 是撞名的官方解。 问题：快照里 pdf、skill-creator、json-canvas 同时存在裸名版与 example-skills:、obsidian: 前缀版——全局命名是稀缺资源。模式：以命名空间前缀发布，把名字的归属权显式化。实证：example-skills:（16 件）、obsidian:（4 件）、glm-plan-usage:（2 件）。要点：给自己的技能起名前，先在快照思维里搜一遍是否撞名。

P6 同名分身：双轨并存是演进的中间态，也是使用者的坑。 问题：skill-creator 在本机以三种形态并存（裸名、example-skills 版、obsidian 版），调用哪个取决于解析优先级，用户未必清楚。模式：对作者而言，迁移期保留双轨可平滑过渡；对使用者而言，安装前要确认会覆盖哪一个。要点：见到同名技能，先查来源再装，别假设「后装覆盖先装」。

P7 前置检查：把 precondition 写进接口。 问题：模糊输入导致技能跑偏，浪费一整轮。模式：在 description 或正文第一步写「调用前先确认什么」。实证：deep-research 的「先问 2-3 个澄清问题」；update-config 用举例枚举兜住模糊表述。要点：宁可 description 多两行，不要运行时多一轮返工。

P8 变体繁衍：一个骨架繁衍一族，是效率也是债。 问题：细分场景（中文版、带链接版、简化版）催生变体，但无治理的变体让用户选择成本暴涨。实证：course-video-maker 衍生 -link、-zh、-zh-link 四件；ericsson-ppt-writer 衍生 -sc、-v2；pptx 裸名系有 generator/manipulation/test/official 五件，外加 example-skills 版，同场竞技六者。要点：变体命名要编码「差异维度」（如 -zh 表语言），避免编码「版本时间」（v2 迟早有 v3）。

四、设计质量评测

说明：本期不采信任何热度数字，评测基于本机可观察的设计证据；「生态可见度」维度以「是否被多命名空间收录/是否繁衍变体/是否内置」作为真实代理信号。

分维度排行： - 描述设计典范榜：code-review ＞ claude-api ＞ update-config ＞ deep-research - 第一个 Skill 学习模板榜：手工最小模板 ＞ skill-creator 生成 ＞ 仿抄官方出厂件源码 - 命名治理观察榜（反面教材）：pptx 六件同场 ＞ course-video-maker 四连后缀 ＞ 裸名/命名空间双轨并存

五、手把手：写出并验证你的第一个 Skill

第一步：先写 description，再写正文。 填三问——用户会说哪句话触发我？输入的前提条件是什么？什么情况明确不适用？

第二步：落盘。 官方技能放在用户级目录即可全局生效：

mkdir -p ~/.claude/skills/commit-message-zh
cat > ~/.claude/skills/commit-message-zh/SKILL.md <<'EOF'
---
name: commit-message-zh
description: 把暂存区的 git diff 写成一条中文 Conventional Commit。当用户说「帮我写提交信息」「commit 一下」且仓库已有已暂存改动时使用。暂存区为空时不适用，禁止自行执行 git add。
---

# 中文提交信息生成

## 步骤
1. 运行 git diff --cached --stat 确认暂存非空
2. 运行 git diff --cached 阅读改动
3. 输出一行 type(scope): 中文描述，重大改动附正文要点

## 边界
- 暂存区为空：提示先 git add，绝不代劳
- 多主题混合：拆成多条建议，不强行合并
EOF

第三步：验证触发。 新开会话，故意说「帮我写个提交信息」看是否命中；再说「帮我把所有文件都提交了」看是否按描述里的不适用条款止步。触发命中与边界拒绝，两条都要测——这正是在给自己的「API」做集成测试。

第四步（可选）：交给元技能。 直接对 Claude 说「用 skill-creator 帮我做一个 XX 技能」，官方元技能会替你走完骨架搭建；想搜索市场上已有的同类避免重复造轮子，用 npx skills find 关键词 定位后再决定是安装还是自写。

新手四个高频错误（对应四条模式）： 1. description 写成宣传语，没有一个可触发的场景句 —— 违反 P1，技能永远休眠 2. 正文塞满背景知识 —— 违反 P2，每轮交上下文税 3. 全散文无脚本 —— 违反 P3，同类任务每次结果漂移 4. 起名撞上已有技能 —— 违反 P5/P6，装完发现行为不对

六、加载链路：理解这四层，模式才有着力点

flowchart TB
    A["用户输入一句话"] --> B{"签名匹配"}
    B -->|"命中 name 与 description"| C["加载 SKILL.md 正文"]
    B -->|"不命中"| D["技能保持休眠"]
    C --> E{"正文是否指向附件"}
    E -->|"需要细节"| F["按需读取 references"]
    E -->|"需要执行"| G["运行 scripts 脚本"]
    F --> H["产出结果"]
    G --> H

P1 决定能否进入第二层，P2/P3 决定第三层加载多少内容，P7 守住第一层的输入质量。八个模式各管一段，合起来才是一条低损耗链路。

参考来源

1. 本机实装技能清单（本会话可见约四百条，含官方出厂件、内置 harness 技能、双命名空间插件） — 本期全部引文与统计数字的第一手来源；文中未标注来源的数量均为对该快照的直接清点
2. anthropics/skills 官方仓库 — 官方出厂件与 skill-creator 的上游入口（本期作为入口索引，未做线上核查）
3. skills.sh — Skills 生态目录与 npx skills CLI 所依托的站点（入口索引）
4. mcpservers.org/agent-skills — 官方与社区 Skills 精选库（入口索引）
5. Claude Code 官方文档 Skills 章节 — SKILL.md 格式与安装路径的权威定义（入口索引）

透明度说明：本期线上榜单类数据未纳入正文，凡涉及 Star 数、下载量、热度排名的信息一律未引用；所有引文均来自标本快照内可见的原文。

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