# 会写技能的技能：七个可抄的写法 ## 概述 这是 Skills 生态定期观察的第八轮。前七轮都在看「别人家的技能」长什么样，这一轮换个位置：不看菜，看菜谱。生态里有一类特殊的技能，它们的工作只有一个——教 Claude 造技能。本期拆了其中两份有代表性的：一份是官方风格的 `skill-creator`，英文写成，工程味重；一份是中文社区的 `skill-factory`，分阶段问答，小白友好。两份样本加上一个装了数百个技能的本地环境里的命名生态，提炼出七个反复出现、可以直接抄走的写法模式。核心发现：好的 SKILL.md 写法高度收敛，收敛到几乎可以列成清单。 ## 先认识两份样本 **skill-creator**：官方系的「造技能流水线」。它不是一篇静态文档，而是一整套带脚本的工作台：写初稿、生成测试用例、带技能和不带技能各跑一遍、出量化基准、开可视化评审页、读反馈、改写、再跑。它甚至内置了一个「description 优化器」，专门用 20 条测试语句去调触发准确率，按 60% 训练、40% 留出的方式防止过拟合。这份样本的价值在于：它把「技能是被测出来的」这件事做成了流程。 **skill-factory**：中文社区的回答。它先把需求分成六大类型——人物视角、工作流、领域专家、代码规范、内容创作、工具集成——每种类型有专属模板和追问清单（每种最多问三个问题），构建完再做三项验证：触发验证、执行验证、边界验证。它有一个很动人的「品味守则」，比如「把通用 AI 能力包装成 Skill（那不是 Skill，只是提示词）」。 一个有意思的细节：skill-factory 的文末署名是「项目地址：github.com/your-repo/skill-factory」——链接是占位符没换。这是社区技能模板化生产的真实痕迹，也提醒我们：生态里的说明书本身，质量也是参差的。 ## 评测对比表 评分基于两份文本本身的设计质量判断，未计入社区热度数据。 | 维度 | skill-creator（官方系） | skill-factory（中文社区） | |------|------------------------|--------------------------| | 功能完整度 | ★★★★★ 起草—测试—评测—优化全闭环，带脚本 | ★★★★ 六类型模板＋三项验证，缺自动评测工具 | | 设计质量 | ★★★★★ 渐进披露、讲理不喊禁令，原则成体系 | ★★★★ 类型识别表与品味守则非常实用 | | 实战效果 | ★★★★ 评测可量化，能对比改进前后 | ★★★ 轻量验证靠人肉执行 | | 上手难度 | ★★★ 英文长文，工程术语密集 | ★★★★★ 中文分阶段问答，新手友好 | | 社区活跃度 | ★★★★ 随官方仓库体系持续演进 | ★★★ 文内未见维护信息，仓库链接仍是占位符 | 七个模式速查： | # | 模式 | 一句话 | 出处 | |---|------|--------|------| | 1 | description 即路由 | 写「什么时候用」，不是「这是什么」 | 两份样本一致 | | 2 | 三层渐进披露 | 元数据常驻，正文按需，资源随取 | skill-creator | | 3 | 目录三分法 | scripts / references / assets 各司其职 | skill-creator | | 4 | 变体拆文件 | 一个框架一个文件，只读相关那份 | skill-creator | | 5 | 讲 why，少喊 MUST | 全大写禁令是一面黄旗 | skill-creator | | 6 | 诚实边界 | 做不到的提前说，拒绝要给得出路 | skill-factory | | 7 | 评测养技能 | 技能是测出来的，不是写出来的 | 两份样本一致 | ## 模式一：description 是路由器，不是简介 两份样本在这一点上完全一致，而且都把它列为最重要的字段。skill-creator 的原话：description 是「主要的触发机制」，要同时写清这个技能做什么、以及什么场景该用它——所有「什么时候用」的信息都放这里，不要放正文。 更有意思的是它给出的两个反直觉细节。第一，模型目前倾向于「触发不足」（undertrigger）——放着现成技能不用。所以官方建议 description 要写得「pushy」一点，它给的正确示范长这样：不只是「如何构建仪表盘」，而是「确保用户提到仪表盘、数据可视化、内部指标，或想展示任何公司数据时都使用本技能，哪怕他们没有明说『仪表盘』这个词」。 第二，触发机制的现实约束：模型只在自己搞不定的任务上才会咨询技能。「读一下这个 PDF」这种一步简单的请求，description 写得再准也可能不触发——因为模型用基础工具就能办。这不是 bug，是设计。 skill-factory 给出了中文世界的四段写法：明确触发词（用户会直接说的短语）、模糊触发词（用户描述需求但没提技能名）、使用场景、以及**不触发的情况**。最后这一段最容易被忽略——写清「什么时候别用我」，和写清「什么时候用我」同样防翻车。 ## 模式二：三层渐进披露 skill-creator 把一个技能的加载结构画成了三层： 1. **元数据**（name + description）：永远在上下文里，约一百词 2. **SKILL.md 正文**：技能被触发时才进入上下文，理想状态五百行以内 3. **打包资源**：按需取用，数量不限——而且「脚本可以不加载就执行」 这三层的经济学含义不同：第一层是所有技能向你收的「常驻税」，装几百个技能，就是几百份 description 一直占着模型的注意力；第二层只在命中时收费；第三层几乎免费，因为脚本跑起来不需要读进上下文。所以写法的推论很直接：正文能短则短，确定性的事情交给脚本去做，不要让模型用散文复述一遍再来一遍。 ## 模式三：目录三分法 官方给出的标准骨架长这样：`scripts/` 放可执行代码，用于确定性和重复性任务；`references/` 放文档，需要时才读入上下文；`assets/` 放产出物要用的文件——模板、图标、字体。 skill-creator 里最实战的一条经验，讲的是怎么发现该往 `scripts/` 里放什么：去看测试运行的完整过程记录——如果三个测试用例里，模型都各自独立写出了一个差不多的 `create_docx.py`，这就是强信号：把它写一次，放进 `scripts/`，让技能直接调用。每一次未来调用都省掉一次重新发明轮子。 这条经验反过来也是排错工具：如果你的技能跑起来又慢又贵，去过程记录里找「模型反复徒手做的事」，那就是该下沉成脚本的事。 ## 模式四：变体拆文件，别一锅炖 当一个技能要支持多个领域或框架时，官方的组织方式是按变体拆目录：`cloud-deploy/` 下一个 SKILL.md 管流程和选择，`references/` 下 aws.md、gcp.md、azure.md 各管一家——「Claude 只读相关的那份参考文件」。超过三百行的大参考文件，要求带目录。 这不只是官方理论。本地环境里就有活例子：`course-video-maker` 这个系列，基础版之外还有 `-zh`、`-link`、`-zh-link` 三个变体；`pcap-analyzer`、`pcap-generator`、`pcap-modifier` 一家三口各管一段；deploy 一族更是 cloudflare、netlify、vercel、render 各一个技能。生态的实践和说明书相互印证：**变体是拆出去的，不是塞在一个文件里用 if-else 写的**。 ## 模式五：讲 why，少喊 MUST skill-creator 写作指南里最值得抄的一句话：「如果你发现自己在用全大写的 ALWAYS 或 NEVER，或者用了超级僵硬的结构，那是一面黄旗——尽量改为解释理由，让模型理解你为什么要这件事。」 它的理由值得展开：今天的模型足够聪明，有很好的心智模型，给出「为什么」之后能举一反三，越过字面指令把事情真正办成；而一摞生硬的 MUST 只能覆盖你想到的情况，没想到的情况全裸奔。配套的还有两条：指令用祈使句；「从反馈中泛化」——如果一个技能只在你的几个测试例子上好使，它就是无用的，与其打补丁式的过度拟合修改，不如换个比喻、换种工作方式重新讲一遍。 ## 模式六：诚实的边界，拒绝要给出路 这是 skill-factory 的主菜。它的好技能标准第二条就是「诚实的边界：做不到的事情提前说清」，并且把「边界验证」设为发布前的必经步骤：给技能一个超出能力范围的输入，检查它有没有明确的边界说明、拒绝时的提示是否有帮助。 它的烂技能清单同样锋利：description 太泛，什么都触发或什么都不触发；执行流程是「帮用户做任何事」；没有检查点，一把梭到底。对照前七轮拆过的各种技能，这三条几乎是所有翻车案例的共同画像。 官方样本在这个问题上对应的是「不惊讶原则」：技能内容不该让用户在知情后感到意外——不藏恶意代码、不做误导性触发。两份样本一柔一刚，说的是同一件事：技能是用户装进自己工作流的长期住户，隐瞒边界的技能住不长久。 ## 模式七：技能是测出来的 skill-creator 的整个后半部分都在讲一件事：写完只是开始。它的闭环是——写初稿，出两三条真实到「用户真的会那么说」的测试句（它的反例教学很直接：坏测试是「格式化这些数据」，好测试是「我老板刚发来一个 xlsx，文件名大概是『Q4 sales final FINAL v2』，她要我把利润率加成一列……」），然后带技能、不带技能各跑一遍，出量化基准，开评审页让人看产出，收反馈，改写，再跑。 它对 description 的优化更狠：生成 20 条测试语句，一半该触发、一半不该触发，而最有价值的不触发样本是「近似误伤」——共享关键词但实际需要别的东西的查询。然后跑自动优化循环，按训练集提建议、按留出集选结果，明确写着「按测试分而不是训练分来选，避免过拟合」。 skill-factory 的中文版答案是三项验证：五个触发句子（两个明确、两个模糊、一个边缘）、一次干跑执行、一次越界测试。轻量，但骨架一致。两份说明书在「测试」上的收敛，比其他任何模式都更说明问题：这是生态用无数次翻车换来的共识。 ## 两个闭环，一张图 三层加载结构： ```mermaid flowchart TD U["用户发来一句话"] --> R{"路由层
description 常驻上下文"} R -->|命中| S["SKILL.md 正文
五百行以内"] R -->|未命中| N["技能不激活
模型裸做"] S --> Q{"还差什么"} Q -->|差规则细节| RF["references
按需读入上下文"] Q -->|差确定性操作| SC["scripts
执行即可不必读"] Q -->|差产出素材| AS["assets
模板素材原样进输出"] ``` 评测闭环： ```mermaid flowchart TD A["写初版技能"] --> B["备三句真实测试话"] B --> C["带技能跑一遍"] B --> D["不带技能跑一遍"] C --> E["并排对比打分"] D --> E E --> F{"达标吗"} F -->|是| G["发布交付"] F -->|否| H["改写 SKILL.md"] H --> B ``` ## 生态侧写：命名里藏着的手艺 本地环境装着数百个技能，命名本身就是一部生态志。最大的一族是人设技能：`-skill` 后缀，从 `luxun-skill` 到 `zhouxingchi-skill`，上百个名字都是「把某人的表达方式做成可复用技能」——对应 skill-factory 六类型里的「人物视角」。最工程化的一族是命名空间：`example-skills:` 前缀下的官方示例、`obsidian:` 前缀下的插件自带技能，冒号前是包名，冒号后是技能名。还有 `skill-creator` 这样在三个包里各上架一份的「畅销书」。 命名的一致性不是强迫症。技能靠 description 做路由，而人靠名字做检索——`kebab-case`、类型后缀、命名空间，这套约定让数百个技能在目录里依然可导航。自己写技能时，起名请遵守同样的纪律。 ## 写你的第一个技能：最小模板 按两份说明书的要求拼一个最小可用模板，五行骨架，直接抄： ```markdown --- name: weekly-report description: 生成周报。当用户提到「写周报」「本周总结」「整理成汇报」， 或要求把 git 记录、待办清单汇总成周报时使用。用户只是闲聊或问日期时不要使用。 --- # 周报生成 ## 执行流程 1. 收集素材：读取用户给的记录，缺的列出来问，不编造 2. 按固定模板分组：本周完成 / 关键数据 / 风险 / 下周计划 3. 输出前自查：每条结论是否有数据支撑，没有的标注「待确认」 ## 边界 - 只整理用户给出的信息，不虚构数据 - 缺失超过三处时，先交问题清单，再写周报 ``` 安装只需把目录放进技能目录——个人级放 `~/.claude/skills/技能名/`，团队共享放仓库的 `.claude/skills/技能名/`，内含一个 SKILL.md 即可，新会话生效。想找现成的技能拆着学，除了官方仓库，各聚合目录站（skills.sh、mcpservers.org 的 Agent Skills 区等）都能按热度翻；用 `npx skills find 关键词` 也可以直接搜市场。最省事的学法还是本期这个：装两三个同题材的竞品技能，把它们的 SKILL.md 摆在一起对读——共识就是模式，分歧就是坑。 ## 推荐排行榜 **第一次写技能，按此顺序抄**：① description 四段法（明确触发、模糊触发、场景、不触发）——五分钟能写完，决定技能生死；② 三层结构意识——正文压在五百行内，细节下沉；③ skill-factory 的三项验证——五个触发句、一次干跑、一次越界。 **团队工程化，按此顺序抄**：① 官方评测闭环——带技能与不带技能双跑对比，这是唯一能把「感觉变好了」变成数字的方法；② 脚本沉淀——过程记录里模型重复手写的东西，一律下沉进 scripts/；③ 变体拆文件——多框架支持从第一天就分目录。 **内容创作者（人设、文风类技能）**：优先模式五和模式六。文风类产出天然主观，测不了硬指标，能依赖的是把「为什么这么写」讲透，以及把「什么时候别用」写清。 一句话收束本期：技能写作的七条共识，其实是三条——**description 决定它会不会被用，结构决定它用起来贵不贵，评测决定它能不能变好**。两份说明书，一本教你像工程师一样造，一本教你像产品经理一样问，合起来才是完整的第一课。 ## 参考来源 1. [anthropics/skills 官方技能仓库](https://github.com/anthropics/skills) — 官方技能库，skill-creator 一系样本的出处 2. [skills.sh](https://skills.sh) — 技能生态站，可查热门榜单与上架动态 3. [mcpservers.org Agent Skills Library](https://mcpservers.org/agent-skills) — 官方与社区技能的精选目录 4. 本机安装副本：skill-creator 与 skill-factory 的 SKILL.md 全文 — 本文所有引文与评分的直接依据 > [!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 等场景全覆盖。