## 概述 第8轮，按系列规划做「设计模式提炼」：不讲某一个 Skill 的功能，而是回答一个问题——**一份合格的 SKILL.md 到底是怎么被设计出来的**。本期做一个此前七轮都没人做过的动作：放弃榜单视角，把标本库换成一台真实工作机上实装的技能快照——本会话可见的技能清单约四百条，含官方出厂件、内置 harness 技能、双命名空间插件和大量社区件，这是一份任何聚合站都爬不到的「真实安装横截面」。从这份快照和内置技能的描述原文出发，本文提炼出八条可复用的 SKILL.md 写作模式，最后手把手带读者写出并验证第一个自己的 Skill。 ## 一、标本库：榜单给不了的真实横截面 榜单看的是热度，快照看的是留存。一个技能被真正装进日常工作机并留下，本身就是比 Star 更硬的信号。先清点这份快照的构成： | 族群 | 数量级 | 代表样本 | |------|------|------| | 角色模仿系（`*-skill` 后缀） | 粗数超过 150 个 | libai、luxun、zhouxingchi、conan | | 官方出厂件（`example-skills:` 命名空间） | 16 件 | skill-creator、pdf、pptx、webapp-testing、mcp-builder | | 内置 harness 技能 | 约 15 个 | code-review、verify、loop、deep-research、claude-api | | obsidian 命名空间插件 | 4 件 | obsidian-markdown、obsidian-bases、skill-creator | | 变体繁衍系 | 多族 | course-video-maker 四连后缀、pptx 五件、部署四件 | | 垂直纵深（电信/笔记/内容产线） | 各 5-10 件 | 3gpp-5g-specs、pcap 三件套、notion 五件 | 这张表本身就是生态的第一课：**命名即分类**。作者群体不约而同用后缀表达「我是哪一族」，而撞名与变体泛滥则是无治理的代价——这两点后文都会变成模式。 ```mermaid 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 设计对照，几乎每一层都能对上： | API 世界 | SKILL.md 世界 | 谁决定 | |------|------|------| | 接口签名 | frontmatter 的 `name` | 作者 | | 路由匹配规则 | `description` 的触发描述 | 作者 | | 实现文档 | 正文 Markdown | 作者 | | SDK / 依赖库 | `scripts/` 目录 | 作者 | | 详细规格书 | `references/` 目录 | 作者 | | 返回类型约定 | 产物形态说明 | 作者 | | 灰度与版本并存 | 命名空间双轨 | 生态 | 这个视角不是比喻游戏——内置技能的 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（内置） | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★★★ | | verify（内置） | ★★★★ | ★★★★★ | ★★★★ | ★★★★★ | ★★★★ | | skill-creator（官方三形态） | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | | obsidian 插件四件 | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★ | | pptx 六件同场 | ★★★★ | ★★★ | ★★★★ | ★★★ | ★★★★ | | course-video-maker 四连后缀 | ★★★ | ★★★ | ★★★ | ★★★ | ★★★ | **分维度排行：** - 描述设计典范榜：code-review ＞ claude-api ＞ update-config ＞ deep-research - 第一个 Skill 学习模板榜：手工最小模板 ＞ skill-creator 生成 ＞ 仿抄官方出厂件源码 - 命名治理观察榜（反面教材）：pptx 六件同场 ＞ course-video-maker 四连后缀 ＞ 裸名/命名空间双轨并存 ## 五、手把手：写出并验证你的第一个 Skill **第一步：先写 description，再写正文。** 填三问——用户会说哪句话触发我？输入的前提条件是什么？什么情况明确不适用？ **第二步：落盘。** 官方技能放在用户级目录即可全局生效： ```bash 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，装完发现行为不对 ## 六、加载链路：理解这四层，模式才有着力点 ```mermaid 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 官方仓库](https://github.com/anthropics/skills) — 官方出厂件与 skill-creator 的上游入口（本期作为入口索引，未做线上核查） 3. [skills.sh](https://skills.sh) — Skills 生态目录与 `npx skills` CLI 所依托的站点（入口索引） 4. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — 官方与社区 Skills 精选库（入口索引） 5. [Claude Code 官方文档 Skills 章节](https://code.claude.com/docs/en/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 等场景全覆盖。