Matt Pocock 是 TypeScript 圈子里很多人熟悉的教育者，他把自己 .claude 目录里的一整套 skill 开源出来，仓库已经到了 17 万星。里面有一个我读完想专门分享的 - writing-great-skills，一个讲“怎么写好一个 skill”的 skill，也是他整套 skills 里我觉得最值得单独拎出来的一个。
Skill 代码仓库：https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills[1]
它的主张一上来就反直觉。很多人以为写好 skill 是为了让 agent 每次输出都一样，但它开篇第一句就把靶子换了：一个 skill 存在的意义，是从随机系统里榨出一点确定性，而这份确定性的名字叫“可预测”- agent 每一次都走同一个过程，不是每一次都产出同一份结果。一个头脑风暴的 skill 应该可预测地发散，它的字词每次都变，但它的行为不变。
这个区分是整套方法论的地基。下面先把它的几根支柱理一遍，再进入最实用的部分 - 六大失效模式。为了不停留在空谈，每一条我都配了一个真实案例：我用这套方法论，实地体检了自己维护的一套视频制作 skill（开源在 sugarforever/boring-video-studio，六个 skill），结果六个坑条条中招。
可预测，不是一致输出
把“可预测”当成根德性之后，很多设计取舍就有了统一的判据。成本、可维护性这些，都是它的副产品，不是和它并列的目标。一条规则值不值得写、一段话该放哪一层、要不要拆成两个 skill，最后都回到同一个问题：它有没有让 agent 的行为方差变小。
理解了这一点，再看它的几根支柱就顺了。
调用方式
一个 skill 怎么被触发，有两条路，各自付不同的代价。
model-invoked（模型可发现）的 skill 保留 description 字段，于是 agent 能自己判断该不该用它，别的 skill 也能引用它，你自己打名字当然也行。代价是它的 description 每一轮对话都躺在上下文里，持续吃 token 和注意力 - 这叫“上下文负担”。
user-invoked（仅人工）的 skill 把 description 从 agent 眼前撤掉，只有你亲手打出它的名字才能触发，别的 skill 也够不着它。它零上下文负担，但换来另一种代价 - “认知负担”：你自己成了那个索引，得记住它存在。
判据很干脆：只有当 agent 必须自己够到这个 skill，或者别的 skill 要引用它，才选 model-invoked；要是它永远只靠你手动触发，就设成 user-invoked，一分上下文负担都不用付。
而当你手动触发的 skill 多到自己都记不住，认知负担就堆起来了。这时候的解药是一个“路由 skill”：一个 user-invoked 的 skill，专门点名其他那些，告诉你各自什么时候该用。它只能提示、不能替你触发，因为那些 skill 根本没有 description。
写 description
model-invoked 的 description 干两件事 - 说清这个 skill 是什么，以及列出哪些分支该触发它。因为每个字都在加重上下文负担，它比正文更该狠删：
- 把 skill 的核心词放到最前面，description 就是它做触发这件事的地方。
- 一个分支一个触发词。用同义词把同一个分支换着说，是重复 - “用 TDD 构建功能…当用户要求测试先行时”其实是同一个分支写了两遍，合并掉，只留真正不同的分支。
- 删掉正文里已经有的身份描述。description 只留触发词，外加一句“当别的 skill 需要…时”的引用说明就够了。
信息层级
一个 skill 由两种内容拼成 - 步骤（steps）和参考（reference），可以全是步骤、全是参考、也可以两者都有。关键决策是每一块内容坐在“信息层级”的哪一层，这个层级按 agent 有多急着用到这块内容来排：
-
“skill 内步骤” - 写在 SKILL.md 里的有序动作，最上面这一层：agent 按顺序做什么。每一步都收在一个“完成标准”上，那个告诉 agent“做完了”的条件。这个标准要可勾选（agent 能分清做完没做完），该穷尽的地方要穷尽（“每一个改动过的项都交代到”，而不是“产出一份改动清单”）- 标准一含糊，就给“过早收工”开了门。
-
“skill 内参考” - 写在 SKILL.md 里、按需查阅的定义、规则或事实。常常是一组平级的东西（一次评审的每条规则都摆在同一层），这是合理的排布，不是毛病。这个
writing-great-skills本身就整个是参考。 -
“外部参考” - 从 SKILL.md 里挪出去、单独成文的参考，靠一个“上下文指针”够到，只在指针触发时才加载。
往下压得太少，顶上就臃肿；压得太多，又把 agent 真正需要的东西藏了起来。这个张力就是整个决策的全部。
这里有个干净的判断法：一个 skill 有几种不同用法，每一种就是一个“分支”。每个分支都要用到的东西留在正文里，只有部分分支才够到的，推到指针后面。而一个指针够不够得到目标，取决于它的措辞，不是它指向谁。
何时拆 skill
拆分粒度是你把 skill 分得多细，每一刀都要花掉两种负担中的一种，所以只在这一刀能挣回来的时候才拆。两种拆法：
- 按调用方式拆 - 当你有一个独立的核心词、它自己就该触发一个 skill，或者别的 skill 必须够到它，才拆出一个 model-invoked 的 skill。你要为它那个永远加载的新 description 付上下文负担，所以这份独立触发得值这个价。
- 按顺序拆 - 当后面还没做的步骤会诱使 agent 草草了结手头这一步（过早收工），就把这段步骤拆出去。让后续步骤离开视野，agent 才愿意在当前这步多下点功夫。
剪枝
- 单一事实源：每个意思只保留一个权威出处，改行为就是改一个地方。
- 逐行查相关性：这行还跟这个 skill 要做的事有关吗？
- 逐句抓“空转行”：一句一句地做“空转测试”- 这句话删了，agent 的默认行为会变吗？不变就是空转。测出空转，整句删掉，别去修字。狠一点，大多数没通过测试的句子该删，不是重写。
核心词
它还有一个很妙的概念 - “核心词”（leading word）：一个已经活在模型预训练里的紧凑概念，agent 在跑这个 skill 时会拿它来思考（比如 lesson、fog of war、tracer bullets）。在正文里反复出现，它就攒起一个分布式的定义，用最少的 token 锚住一整片行为，因为它调动的是模型本来就有的先验。
它为可预测服务两次。在正文里它锚住执行：每次这个词出现，agent 都伸手去做同一件事。在 description 里它锚住触发：当同一个词也活在你的 prompt、文档、代码里，agent 就把这套共同语言和这个 skill 绑起来，触发得更稳。
它给的例子很生动：把“快、确定、低开销”收成一个词 tight（一个 tight 的循环）；把“一个你信得过的循环”收成 red（循环遇到 bug 就变红，要么红要么不红）。你赢两次 - token 更少，agent 挂思考的钩子也更利。
以上是骨架。而这个 skill 里专门有一节叫“失效模式”（Failure modes），一口气列出了六个最常见的坑 - 这也是全篇最实用、最能让人对号入座的部分。下面每一条，我都配一个体检 boring-video-studio 时抓到的真实例子。
过早收工（premature-completion）
原则：一步还没真做完就结束，注意力溜到了“做完”这件事上。防它的顺序是：先收紧完成标准（便宜、就地）；只有当标准实在没法再精确、而你又确实观察到 agent 在赶工，才用拆分把后续步骤藏起来。
真实案例：我那套 skill 里管字幕校正的 listenhub-tts，校完字幕这一步的完成标准写成了“先抽看几条，没问题就直接进下一步”。什么叫“没问题”？抽看“几条”是几条？都没定义。agent 完全可以扫一眼就宣布通过。对照一下同一套里编排层 blockframe-video 的完成标准 - “结束前跑 check-deliverables.sh 验收，有一个 ✗ 就是没完成”，一个脚本、一个二值结果，agent 想赖都赖不掉。同一套 skill，两种完成标准，高下立判。
修法：把“没问题就进”换成能勾选的条件，比如“首尾各三条字幕的时间戳与音频对齐、没有空条，才算通过”。
重复（duplication）
原则：同一个意思出现在不止一个地方。它既费维护也费 token，还会把这个意思在信息层级上的位置抬得比它实际该有的高。
真实案例：“封面是一套不是一张”这条规则，在我 blockframe-video 这一个 skill 里，前后出现了六次 - description 里一次、开头铁律里一次、分工表里一次、第四步里一次、避坑清单里一次、验收清单里再一次。当初每加一处都觉得“多提醒一遍更保险”，累积下来，同一句话占了六份 token，以后想改口径得改六个地方，漏一个就自相矛盾。
修法：一条规则只在一个权威位置说全（比如放进验收清单），别处要提就引一下，别整段复述。
沉积（sediment）
原则：陈旧的层因为“加着安全、删着有风险”而一层层沉下来。任何没有剪枝纪律的 skill，默认的下场都是沉积。
真实案例：这是最典型的一个，我自己看到都愣了一下。blockframe-video 早期竖版画面用一种叫 zoom:2 的“真·超采样”办法出 4K，后来这套办法被换成了普通的 lanczos 放大 - 但当年那句“3:4 出 4K 超采样”的说法，只删掉了一部分。于是同一个文件里，前面两处还写着“含 3:4 的 4K 超采样”，后面却有一句老老实实的更正：“诚实说，这是高质量原生渲染加 lanczos 放大，不是真·超采样”。一个文件，自己跟自己打架 - 被删掉的旧层没清干净，留下了这摊沉积。类似的还有：同一个竖版成片，在文件里前后出现了四种不同的文件名。
修法：主动剪枝。旧办法一旦换掉，就把它带出来的所有措辞、数值、文件名全局搜一遍，统一成新的说法（比如竖版一律叫“1080×1440 原生 + lanczos 放大”），别让旧层沉在那儿。
膨胀（sprawl）
原则：一个 skill 单纯就是太长了，哪怕每一行都还活着、都不重复。它伤可读性和可维护性，也浪费 token。解药就是信息层级：把参考用指针挪出去，按分支或顺序拆开，让每条路径只扛它自己要的那部分。
真实案例：producing-video 这个 skill 长到了 255 行，光“避坑”一节就堆了 17 条，每条还都是一整段；blockframe-video 291 行，10 条避坑，里面不少还和正文的流程重复。它俩早就不像一张“技能卡”，更像一本参考手册 - agent 每次加载都得从这一大坨里翻。
修法：把那份详尽的避坑目录用披露挪到单独的 references/gotchas.md，SKILL.md 正文只留主流程加最狠的三四个坑，按需再去查那份清单。
空转行（no-op）
原则：一行 agent 本来就默认会照做的话，你却花上下文负担说了句废话。测试很简单：它相对默认行为改变了什么吗？一个软弱的核心词（agent 本来就够仔细，你还写“要仔细”）就是空转；修法是换一个更强的词（relentless），不是换一种技巧。
真实案例：finance-stock-video 里有个小标题写着“第一步 · 数据采集与核实（本 skill 的核心，别省）”。这个“别省”就是空转 - 它本来就是编号第一步，agent 根本不会跳过它，这两个字改变不了任何默认行为，纯占位置。同类的还有“事实必须实证…别编”里的“别编”、“用户很在意准确”这种打气的话。
修法：逐句做空转测试，把这些删了行为不变的祈使句直接删掉，只留具体动作。
否定式（negation）
原则：靠禁令来引导会反噬 - “别想大象”这句话恰恰点了大象的名，让它更容易被想起，而不是更少。要正着提：把目标行为说出来，让被禁的那个从头到尾不被提及；只有当一条禁令你实在没法正着说，才留着它当硬护栏，而且即便如此也要配上“那该怎么做”。
真实案例：blockframe-video 里那句“竖版固定 3:4，不要做 9:16…别再漂回 9:16”。你想让 agent 做 3:4，可你反复念叨的是 9:16，等于一直在它耳边点这个不想要的选项的名。“别再漂回”更是把禁令又重复了一遍。
修法：正着说目标。把主画布直接定义成“竖版主画布 = 3:4，1080×1440”，让 9:16 从头到尾不被提起，那句“别再漂回”也就没必要了。
一份 skill 自检清单
把这套方法论收成一张你写完 skill 可以逐条过的清单：
- 触发：这个 skill 该被 agent 自己发现（model-invoked，付上下文负担），还是只靠我手动触发（user-invoked，零负担）？手动的多到记不住了吗 - 该上路由 skill 吗？
- description：核心词在最前面吗？有没有把同一个分支用同义词写了好几遍？正文里已有的身份，description 里删干净了吗？
- 完成标准：每一步的“做完了”都可勾选吗？该穷尽的地方写成“每一个都交代到”了吗，还是留了“产出一份清单”这种含糊话？
- 信息层级：每个分支都要用的留在正文了吗？只有部分分支够到的，推到指针后面了吗？指针的措辞，够不够稳地把 agent 引过去？
- 剪枝：逐句做过空转测试吗？有没有同一个意思散在好几处（重复）？有没有和别处打架的旧值（沉积）？
- 措辞：有没有靠禁令引导（否定式）？能不能改成正着说目标行为？
- 长度：整体是不是就是太长了（膨胀）？能不能靠披露和拆分让每条路径只扛自己那份？
方法论说到底就一句：像对待代码那样对待你的 skill。先证明问题真实存在，再写最小的解，然后逼自己逐句、逐值地剪。我拿它体检自己那套 skill 的结果已经说明，哪怕是你天天在用、以为写得挺干净的 skill，六个坑也照样条条能踩。
References
- writing-great-skills: https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills
这里给大家精心整理了一份全面的AI大模型学习资源，包括：AI大模型全套学习路线图（从入门到实战）、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等，资料免费分享！
👇👇扫码免费领取全部内容👇👇
1. 成长路线图&学习规划
要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。
这里，我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。
2. 大模型经典PDF书籍
书籍和学习文档资料是学习大模型过程中必不可少的，我们精选了一系列深入探讨大模型技术的书籍和学习文档，它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。（书籍含电子版PDF）
3. 大模型视频教程
对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的大模型视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。
4. 2026行业报告
行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。
5. 大模型项目实战
学以致用 ，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。
6. 大模型面试题
面试不仅是技术的较量，更需要充分的准备。
在你已经掌握了大模型技术之后，就需要开始准备面试，我们将提供精心整理的大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。
7. 资料领取：全套内容免费抱走，学 AI 不用再找第二份
不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：
👇👇扫码免费领取全部内容👇👇
扫一扫
532
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
