会写技能的技能：七个可抄的写法

概述

这是 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」——链接是占位符没换。这是社区技能模板化生产的真实痕迹，也提醒我们：生态里的说明书本身，质量也是参差的。

评测对比表

评分基于两份文本本身的设计质量判断，未计入社区热度数据。

七个模式速查：

模式一：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 的中文版答案是三项验证：五个触发句子（两个明确、两个模糊、一个边缘）、一次干跑执行、一次越界测试。轻量，但骨架一致。两份说明书在「测试」上的收敛，比其他任何模式都更说明问题：这是生态用无数次翻车换来的共识。

两个闭环，一张图

三层加载结构：

flowchart TD
    U["用户发来一句话"] --> R{"路由层<br/>description 常驻上下文"}
    R -->|命中| S["SKILL.md 正文<br/>五百行以内"]
    R -->|未命中| N["技能不激活<br/>模型裸做"]
    S --> Q{"还差什么"}
    Q -->|差规则细节| RF["references<br/>按需读入上下文"]
    Q -->|差确定性操作| SC["scripts<br/>执行即可不必读"]
    Q -->|差产出素材| AS["assets<br/>模板素材原样进输出"]

评测闭环：

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、类型后缀、命名空间，这套约定让数百个技能在目录里依然可导航。自己写技能时，起名请遵守同样的纪律。

写你的第一个技能：最小模板

按两份说明书的要求拼一个最小可用模板，五行骨架，直接抄：

---
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 官方技能仓库 — 官方技能库，skill-creator 一系样本的出处
2. skills.sh — 技能生态站，可查热门榜单与上架动态
3. mcpservers.org Agent Skills Library — 官方与社区技能的精选目录
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 等场景全覆盖。