SKILL 18 / WRITING · DEEP DIVE

写作 Skill 的通用配方:样例压过规则

三对胜过十条 · 每条规则配 1–3 对(上限就是 3) · 以及官方那个叫 examples/ 的目录里其实没有样例

2026-09-19 · BigCat

「写得简洁点」是一条规则,它在你脑子里有取值,在模型那儿没有。样例模式解决的就是这件事:不描述标准,直接把标准的两个端点贴出来。本期把四份能点开的实物拆开数了一遍——包括一个数得出来的答案:一条规则该配几对样例。

前置 → Skill 17 「去 AI 味」类 Skill(本期的样例实物多半出自那几份清单)

// WHY THIS MATTERS

先交代一笔账。路线图给本期定的范本是官方 brand-guidelines 与 doc-coauthoring 里的「样例段」。两份我都拉下来逐行读了:brand-guidelines 全文 73 行,一个样例都没有;doc-coauthoring 375 行,里面的样例是写给人看的,教你怎么回话,不是给模型看的范文。所以可抄的模板不在这两份里——它在官方 best-practices 文档的「Examples pattern」一节,和两个社区 skill 的实物里。而这个落差本身就是本期第一条判据:不是所有 skill 都该有样例。下面的行数、对数全是我今天从 main 分支原文数的,不是从聚合站抄的。

// 01

它替你干掉什么:让形容词有取值

论断:样例干掉的不是「写规则」这道工序,是「形容词没有取值」这个病。「简洁」「有力」「别营销腔」这些词,你和模型的取值范围不一样,而一对 before/after 把范围钉死在纸面上。

照抄这一节就够开工:官方 Skill authoring best practices 的「Examples pattern」给了一份完整范本,主题是 commit message,正好三对,形式是 Input: 一句自然语言描述 / Output: 一段代码块,三对之后用一句「Follow this style: type(scope): brief description, then detailed explanation.」收口。该节的结论原文是:

Examples convey the desired style and level of detail to Claude
more clearly than descriptions alone.

(据 platform.claude.com 该页,2026-09。)它替你干掉的是「写个好 commit message」这种没法验收的要求——三段可比对的实物一贴,验收标准就在那儿了。

怎么用

官方 skill-creator(anthropics/skills · skill-creator)里有一份精简版的同名段落,可以直接抄结构。它还多给了一句提醒:「if "Input" and "Output" are in the examples you might want to deviate a little」——别把 Input: / Output: 这两个字面量原样留在成品里,模型会连标签一起学走。

第一条立刻能跑的用法:打开你最近一篇被退回重写过的稿子,原稿贴进 Before、定稿贴进 After,中间补一行「这次改了什么」。一对就能用,不用等凑齐三对。真实退稿比现编的样例强,理由见第 03 节。
进阶资源 · Anthropic · Skill authoring best practices(「Common patterns」章下并列 Template pattern / Examples pattern / Conditional workflow pattern 三节,2026-09)
// 02

机制:规则给禁区的名字,样例给禁区的边界

论断:规则和样例不是二选一。blader/humanizer 把两者焊成了一个四槽单元,那才是本期最该抄走的最小件。

四槽单元 · blader/humanizer

blader/humanizer(MIT,SKILL.md 内标 v3.0.0)装法是 npx skills add blader/humanizer --global,去掉 --global 就只装当前项目,装完喊 /humanizer。它列了 25 条编号句式,每条的写法固定四槽:Watch for:(怎么认出来)· Problem:(为什么算病)· Before: · After:。前两槽是规则,后两槽是样例,规则负责命名,样例负责划界。第 1 条 Not X but Y 的实物长这样:

Before: It's not just about the beat riding under the vocals;
        it's part of the aggression and atmosphere.
After:  The heavy beat adds to the aggressive tone.

(据该仓库 main 分支 SKILL.md,2026-09。)它替你干掉的是「这句读着像 AI」这种说不清的判断——四槽一贴,判断降级成模式匹配。什么时候别装:技术文档仓库里常开别装,它删的副词正是你要的精确性(这条 Skill 17 已经展开过)。

多加一行注解 · stop-slop

boraoztunc/skills · stop-slop(393 行)走的是另一条路:句式清单在前,末尾挂一个独立的 ## Examples 块,5 对,而且每对后面多一行 Changes:,例如「Removed opener, binary contrast structure, and emphasis crutch.」

这一行才是让样例可迁移的东西:只给 before/after,模型可能学成「短句好」;补上 Changes:,它学到的是「删的是开场白和二元对比」。大多数人写样例时正好漏掉这一行。用法就是抄它那个三行结构(Before / After / Changes)。什么时候别装:它和 humanizer 抢同一个触发面,两个同时挂文风每次都变,挑一个。

官方对样例本身的三条标准

官方 Prompting best practices 的「Use examples effectively」一节给了三条:relevant(贴近你真实的活)· diverse(要覆盖边角、彼此拉开,原文的理由是「vary enough that Claude doesn't pick up unintended patterns」)· structured(用 <example> 标签包起来,让模型能把样例和指令分开)。页面给的数量建议是 3–5 对(据 platform.claude.com 该页,2026-09)。

反例:什么时候一条规则就够

anthropics/skills · brand-guidelines 全文 73 行,零样例。它的约束是 #d97757、#141413、标题用 Poppins、正文用 Lora——hex code 不需要样例,它本身就是验收标准。一条约束能一句话写死取值的,写规则;写不死的,才轮到样例。这就是第 03 节那张判据表的第一行。

// 03

真实用法与边界:几个够、怎么选、放哪

论断:「几个够」有一个能数出来的答案,而且答案不是总量——是每条规则 1–3 对,上限就是 3。

几个够:把实物数一遍

我把 blader/humanizer 的 27 个二级段全数了一遍(据 main 分支 SKILL.md,2026-09):25 条句式里,14 条各配 1 对、9 条各配 2 对、2 条各配 3 对,另外 2 个纯流程段(Voice / What to return)0 对。没有任何一条超过 3 对。和官方「3–5 examples」的口径合起来读就清楚了:3–5 说的是一次判断里模型能用上的总量,落到单条规则上,实际是 1–3——句式越难认的配 2–3 对,一眼能认的配 1 对就停。

作者自己在做减法:blader/humanizer 的 README changelog 里,v2.9.1 那条写着删掉了「a repeated long example」。样例不是越多越好,多出来的那对只是在交 token 税。

怎么选:从退稿里选,别现造

skill-creator 把这个坑写在了正文里(据 main 分支 SKILL.md,2026-09):「if the skill you and the user are codeveloping works only for those examples, it's useless」。它警告的正是拿两三个样例反复迭代迭出来的过拟合——你和模型一起把那几段打磨到完美,换一篇就废。解法是选材:从你真实退回过、真实改过的稿子里取,再按官方那三条过一遍(relevant / diverse / structured)。

放哪:SKILL.md 里最贵的就是样例

官方给的上限是 SKILL.md 正文 500 行,而样例是其中字数最多、最难压的部分。解法是 progressive disclosure——样例挪进子文件,SKILL.md 只留路由。anthropics/skills · internal-comms 是这个做法的极端实物:SKILL.md 只有 32 行,正文就是一张路由表,按通讯类型分别去读 examples/3p-updates.md(46 行)· examples/company-newsletter.md(65 行)· examples/faq-answers.md(29 行)· examples/general-comms.md(15 行)。它替你干掉的是「写周报/公司通讯每次都要重新解释格式」;怎么用是把它整份拷进你的 skill 目录再换掉四份格式;什么时候别装——它的取数完全指望 Slack / Drive / 日历 MCP,这些没接就只剩排版。

但这里必须说实话:那个目录虽然叫 examples/,装的不是 input/output 对,是每类通讯的格式规格。company-newsletter.md 里那个 ## Example Formats 节,内容字面就是「- Announcement 1 / - Announcement 2 / - Announcement 3」——给的是骨架,不是范文。为什么?真实的公司内部通讯不能进公开仓库。这不是偷懒,是硬约束,而且你有同一条约束:别把客户稿和内部稿塞进 public repo 当样例。

被忽略的反向用法:给人看的样例

anthropics/skills · doc-coauthoring(375 行)的样例全在输入侧。Step 3 Curation 那节直接列了四条回话范例:「Keep 1,4,7,9」「Remove 3 (duplicates 1)」「Remove 6 (audience already knows this)」「Combine 11 and 12」。原文写明要 request brief justifications,目的是 learn priorities for the next sections——它用样例教的是人,好让人的反馈变成它能学的形式。怎么用:任何需要你反复给反馈的 skill,都值得加三条回话范例;什么时候别装:它是个从头陪写长文档的全流程 skill,你只想润色一段的话,开它是杀鸡用牛刀。

// 04

代价与替代品:三笔账,第三笔没有解

论断:样例要付的是过拟合、token、同化三笔账。前两笔官方都给了解法,第三笔没有——而且它不报错。

第一笔,过拟合。官方自己写进了 skill-creator(上一节引过)。解法有:样例要 diverse,写完拿一个没见过的任务试一遍。

第二笔,token。样例是 SKILL.md 里最占地方的部分,撞 500 行上限的多半是它。解法是 internal-comms 那个 32 行路由表——样例进子目录,用到哪份读哪份。

第三笔,同化——这笔没有解。样例会变成天花板:模型不会交出比你那段 After 更好的句子,因为它优化的就是「像那段」。你挑的样例是你半年前的水平,半年后它还在按那个水平交付,而且一切正常、没有任何报错。唯一能做的是定期换样例。blader/humanizer 从 35 条合并成 25 条、又删掉一个长样例,走的正是这条路——样例库和 skill 一样会过期,只是过期了不会告诉你。

不写样例,你还能怎么办

  1. 写规则——约束能一句话写死取值时。实物是 brand-guidelines:73 行、零样例、全是 hex code 和字体名,这是对的做法。
  2. 写模板——官方 best-practices 的 Template pattern:给输出骨架而不是范文。严格版原文用 ALWAYS use this exact template structure,宽松版用 a sensible default format, but use your best judgment。internal-comms 里那个 ## Example Formats 其实就是这一类。
  3. 写校验——官方的 feedback loop(跑校验 → 改 → 再跑)。能写脚本验的东西别用样例教,样例只在「机器验不了」的地方才有价值。

// 选购卡

先抄这三样(都是具体文件,不是方法论):① 结构抄官方 best-practices 的「Examples pattern」节——三对、Input/Output、末尾一句 follow this style 收口。② 单元抄 blader/humanizer 的四槽:Watch for / Problem / Before / After,每条规则配 1–3 对。③ 注解抄 boraoztunc/skills 的 stop-slop:每对后面加一行 Changes:,写明这次删了什么。

目录怎么摆:照 internal-comms——SKILL.md 只留路由表,样例全进子目录。但别学它把格式规格命名成 examples/,那个目录名骗了不少人。

明确别写样例:约束是 hex code / 字体名 / 固定命令这种一句话能写死的(brand-guidelines 零样例是对的)· 你手上只有两稿而且是同一个人同一天写的(diverse 不满足,必过拟合)· 样例含客户或公司内部内容而仓库是公开的(internal-comms 没有真范文就是这个原因)。

写完自检三问:这条约束机器能验吗?能 → 写脚本。能一句话写死取值吗?能 → 写规则。都不能、但你拿得出两稿对照吗?→ 写样例,并且补上那行 Changes:。

// 术语表

few-shot / multishot(少样本提示)
在指令里塞几对做好的输入输出,让模型照着办。样例模式就是把这招固化进 SKILL.md。官方给的数量是 3–5 对。
Examples pattern(样例模式)
官方 best-practices「Common patterns」章下的一节:输出质量取决于「见过范本」时,就给 input/output 对。
Template pattern(模板模式)
同一章的邻居:给输出骨架(章节名、占位符)而不是范文。约束的是结构,不是文风。
progressive disclosure(渐进披露)
SKILL.md 只留路由,细节进子文件、用到才读。internal-comms 的 32 行正文是这招的极端实物。
overfitting(过拟合)
skill 只在你反复打磨的那几个样例上好使,换一篇就废。skill-creator 把这条警告写进了正文。

// 延伸阅读