如何写 Skill 第3课,正文不是文档,是快照

找到了,不等于做对了。上一篇说到,模型决定要不要用你的 skill,看的只有 description 那一句;这一篇补后半句——它把你的 skill 加载进来之后,再也不会回来读第二遍。SKILL.md 的正文不是文档,是一次性注射、跨轮留存、逐行计费的快照。你给这份快照写的每一行规矩,都得按"没人会核对第二遍"来写。

背景一句话:模型"觉得相关"触发 skill 的那一刻,渲染后的 SKILL.md 正文作为一条消息整体进入对话,之后每一轮都在场。官方原话:"the rendered SKILL.md content enters the conversation as a single message and stays there across later turns."但这份在场是一次性的——官方同样写明:"Claude Code does not re-read the skill file on later turns."模型看的是进上下文那一刻的快照;之后你在磁盘上怎么改,本会话一概不知。

本文案例取自本机真实已装的 skill;tdd、pr、code-review 等公开范例实名引用,自研部分已脱敏,名称替换为 A/B,内部编号改写成机制描述;引用的官方行为均出自 code.claude.com/docs 的 Skills 页(2026 年 10 月核对)。

快照的一生还有三段,规矩全从这里面长出来。第一段,再触发:同样内容再次触发,只在对话里追加一条说明,不重贴全文;内容变了(新参数、新输入)才重新附加。第二段,压缩:上下文被压缩时,每个活跃 skill 只回附正文开头,每个 skill 前 5000 token,合计 25000 token 封顶;快照后半截被吃掉的细则就地失传,没有"翻原文"这回事。第三段,计费:正文一旦加载,每一行都是逐轮复发的常驻成本——上一篇里整张 skill 清单常驻常在,也才占上下文的 1%;正文降了一档,是"触发之后"每轮都在场。五条事实压成一句:模型只看一眼,但看一眼就要管到底。

常驻性:写"每次都该遵守",别写"只此一次"。 既然不重读,一条指令的适用时机就必须写在字面上。官方给的原型病句和原型改法正好是一对:写 "Run the tests after every edit",别只写 "Run the tests"。"运行测试"第一轮被执行一次,之后沉在上下文深处,语义里又不含时机——意图是常驻规则,措辞是一次性步骤,这类指令会腐烂:文件里还在,任务里已经死了。边界要说清:真正一次性的步骤(装依赖、初始化)写成一次性完全合法;病,专指意图常驻却写成一次性的那种。本机一个 38 行的 tdd skill,正文开头就有一句相当自觉的话:"Every section applies on every cycle: consult them before and during the loop, not after."——把"每一节都常驻"直接说破,替模型省了判断。这条问的锚,就是"不重读":时机不写在字面,第一轮之后就没人替你记得。

简洁性:说做什么,别叙述怎么做、为什么。 官方原话:"State what to do rather than narrating how or why, and apply the same conciseness test you would for CLAUDE.md content."——拿你给 CLAUDE.md 内容的那把简洁标尺来量。逐行计费的机制下,大段叙述是纯损耗——这条问的锚就是那笔账。但这条规则有一个例外,例外比规则本身有信息量,后面单开一节讲。

归属:正文、参考文件、脚本,三选一。 essentials 留正文;大参考、示例集下沉成单独文件,且正文里必须显式点名——官方给的句式是 "For complete API details, see reference.md."。确定性操作干脆做成脚本:脚本被执行,不进上下文,官方的说法是 "The bundled script does the work while Claude handles orchestration."(脚本干活,Claude 负责调度。)大参考的好处官方也点破了:"Large reference material costs almost nothing until you need it."——没人用,就几乎不花钱。这条问的锚是渐进披露的老账:常驻的每一行都贵,不该常驻的别赖在正文。

行数:500 行是官方画的线。 原话:"Keep SKILL.md under 500 lines. Move detailed reference material to separate files."超线不是死刑,下面有个 1004 行的活标本,但超了线又没有自救装置的,该瘦身了。这条问的锚还是常驻成本:行数是它最粗的刻度。

四问是尺子,拿去量本机在装的五个 skill,行数全部 wc -l 实测:

tdd,38 行。 概念定义、反模式、循环规则;示例下沉 tests.md / mocking.md 并在正文点名。极简三段式,常驻措辞的自觉样板。

code-review,87 行。 五步编号流程 + 12 条 smell 基线 + 被点名的 "Why two axes"。task content 的教科书。

pr,163 行。 PR 描述模板即正文,每节配判决式指导("Skip all preambles")。模板型 skill:正文就是模板加约束。

docx,315 行。 任务/场景双路由表给参考文件编址;速查留正文,全表下沉。正文是目录,不是仓库。

pdf,1004 行。 Triage 分级 + 预路由检查 + 路由决策树。超官方线一倍的活标本。

谱系自己会说话:38 行的 tdd 是"参考型 skill"的克制,查规则的;1004 行的 pdf 是"工作台型 skill"的重装,干活的。docx 的双路由表值得单看一眼:正文自己不装货,装的是"什么任务去读哪个文件"的编址,任务类型指到 routes/、行业场景指到 scenes/。

pdf 超线一倍还活得好好的,靠的是自救装置:开篇一张 Triage 表,把任务分成 Light 和 Standard 两档,轻任务只载正文加一个流程文件,大块的排版资源碰都不碰。超线不可怕,超线又没有分级装置才该瘦身——第四问量完行数,要找的就是这个东西。

该兑现前文的钩子了:简洁性有一个例外,而且例外比规则有信息量。code-review 的正文里有一节 "Why two axes",整整六行,纯叙述——解释为什么评审要分"规范"和"规格"两条轴跑,没有一条指令。拿简洁标尺量,它该删。但通读全文会发现第 5 步里有一句:"Do not merge or rerank findings, because the two axes are deliberately separate (see Why two axes)."——把两份报告合并、强行排出总名次,正是这节要防的错误模式;那六行是这条禁令的依据,删了它,"不许合并"就成了没来由的霸道。判定式可以说得很干净:被正文其他步骤点名引用、防着某个具体错误模式的 why,是常驻规则的依据,不是装饰;简洁测试的靶子是用叙述代替指令,不是一切叙述。

这套四问做过一轮实测,不是纸面推演,先报成绩:四个全新上下文的模型并行开跑——一个只拿五条摘录盲判(不含任何答案),两个分别通读 tdd 和 code-review 全文跑四问,一个对自家两个 skill 做诊断——盲判的分数是 3/5。装置不复杂,含金量在错的那两题上。盲判者判 "Why two axes" "该删",判 pdf "超线且无自救",恰好全错。根因是同一个:"被谁引用"和"有没有分级装置",都不在摘录里。 通读全文的那个模型,grep 一把找到第 5 步的引用,对同一段的结论当场反转:"符合例外三条件,可留。"pdf 那条同理:上一节你看过的那张 Triage 表,不在摘录里,盲判者只看得见 1004 这个数。全文审计的代价也摆在桌面上:盲判一跑 3.7 万 token,全文一跑 15 到 25 万;信息集的大小,直接换判定的边界。

所以四问有一条使用前提:检查单必须跑在 SKILL.md 全文上。 摘录式审计只能查常驻性和简洁性的表层,例外条款和分级装置都是全文级判定。要考别人"会不会判例外",就得给全文,出题同理。

归属还有下半场。正文点名的那些文件,自己也会点名别的文件,所以可达性问的不是"正文提没提到它",而是"从模型可见的链路能不能走到它"。本机两个自研 skill(脱敏,称 skill A、skill B)正好一正一反。A 是正面样本:正文只点名一个文件,编排器;编排器点名规则文件和五个阶段文件;阶段文件再点名模板和参考——十一个正文从未提及的文件,沿链全部可达,零孤儿。B 反着来:一个 readme.txt 孤悬链外,十几行的架构摘要,没有任何文件提到它。加载机制的契约里只有 SKILL.md 一个入口,链外的文件写得再好,模型一眼也看不见。没点名不等于不可达,这中间的差距正是薄壳调度存在的理由——薄正文、编排器、阶段文件、参考模板,层层编址,正文越薄,链反而越走得通;而真断了链的死文件,互相引用得再热闹,也是一个模型永远走不进去的闭环。

验证的办法也是最笨的那种:逐环 grep。从正文出发顺着点名一路走,走不到的就是死的。

顺带一例 skill A 的真实病灶,正好给这节收尾:它的模式判定表在正文和编排器里各存了一份,两边的关键词集已经漂移——"看看"这个词只在编排器那份里有。双份维护的东西,漂移只是时间问题;归属的另一面由此补全:同一信息,只配一个家。

实操:给你的 skill 正文跑一遍四问。输入是任一已装 skill 的 SKILL.md 全文,按固定顺序四步。

第一步,量行数。 wc -l 一下,超 500 的先标出来,知道往哪使劲,后面三问才有轻重。

第二步,逐条指令标常驻性。 每条标注:常驻规则 / 真一次性 / 腐烂(意图常驻、写成一次性),记下行号。标进"腐烂"那批的,就是第一轮修复对象。

第三步,查简洁与归属。 找叙述段,每段问一句:被谁点名引用?防着什么错?答不上来的,记下行号,删或下沉成参考文件;再查大参考段的点名句在不在、引用链通不通、哪些操作该改成脚本。

第四步,复核分级装置。 超线的,找出它的 Triage 在哪几行;找不出的,回第三步决定下沉什么。

输出是一张带行号引用的病灶清单。四问全部有证据而清单为空,同样是合法结果:那时你手里握着的是四问全过的证据。

带走三样

• 正文是一次性注射、跨轮留存的快照:单条消息进场,永不重读,压缩只回附开头 5000 token,每一行逐轮计费——模型只看一眼,但看一眼就要管到底。
• 检查单四问:常驻性(时机写满字面,别让指令腐烂)、简洁性(叙述该删,除非被点名引用且防着具体错误)、归属(正文 / L3 显式点名 / 脚本)、行数(500 线,超线找分级装置)。
• 两条铁律:检查单必须跑全文,例外和装置是全文级判定,摘录判不了;归属跟着机制走,谁要被整段粘贴、谁要跨轮常驻,谁就留在正文。

临走三问(凭记忆,别往上翻)

• 一问:正文里写着"运行测试",真实意图是每轮编辑后都跑——按官方处方,这句该怎么改?
• 二问:一段六行的纯叙述 why,没有一条指令,什么条件下可以名正言顺地留在正文?
• 三问:一个 skill 正文 800 行,开篇有张分级表,轻任务只载正文加一个流程文件——第四问判它什么?

如果喜欢，请关注我吧。