原始 GitHub 文件SKILL.mdGLOSSARY.md这篇文章复现 Matt Pocock 的writing-great-skills。目标是让读者同时得到两件东西先拿到一套完整中文 skill 文件至少包含SKILL.md和GLOSSARY.md两份核心文件。再看懂原SKILL.md里真正容易读浅的设计难点。可读性更高的SKILL展示writing-great-skills1. 完整可复制中文 SKILL.md主文件下面是第一份核心文件也就是可直接复制为SKILL.md的中文版本。它保留原 skill 的结构和行为但用中文重写。--- name: writing-great-skills description: 写作和编辑高质量 skill 的参考提供让 skill 行为更可预测的词汇和原则。 disable-model-invocation: true --- Skill 存在的目的是从随机系统中争取确定性。**可预测性** 指 Agent 每次运行时采用同一种过程而不是产出同样的文本。下面所有杠杆都服务于这个目标。 **加粗术语** 的完整定义应放在 GLOSSARY.md 中当你不确定术语边界时先查术语表再修改 skill。 ## Invocation 先决定这条 skill 由谁触发。两种选择花费不同成本 - **Model-invoked** skill 保留 **description**这样 Agent 可以自动触发它其他 skill 也可以触达它用户仍然可以手动点名。代价是 **context load**description 会在每轮对话里占用上下文窗口和注意力。机制上不设置 disable-model-invocation并写面向模型的 description包含明确触发措辞例如 “Use when the user wants...” 或 “Use when the user mentions...”。 - **User-invoked** skill 对 Agent 隐形只能由用户输入名称触发其他 skill 也不能自动触发它。它没有 context load但会消耗 **cognitive load**用户自己必须记住它存在并知道什么时候使用。机制上设置 disable-model-invocation: truedescription 变成人类摘要只写一句说明不写触发清单。 只有当 Agent 必须自己想起这条 skill或其他 skill 必须能触达它时才选择 model-invocation。如果它只会由用户手动调用就做成 user-invoked避免支付 context load。 当 user-invoked skills 多到用户记不住时用一个 **router skill** 处理 cognitive load这个 user-invoked skill 只列出其他 user-invoked skills 以及什么时候该用它们。 ## Writing the description model-invoked 的 **description** 有两个职责说明这条 skill 是什么以及列出哪些 **branches** 应该触发它。description 中每个词都会增加 context load所以它比正文更需要修剪 - **把 leading word 放在前面**description 是 leading word 发挥 invocation 作用的地方。 - **每个 branch 只保留一个 trigger**同义词如果只是重命名同一个 branch就是 **duplication**。例如 “build features using TDD” 和 “asks for test-first development” 通常是同一个 branch 写了两遍。合并它们只保留真正不同的触发分支。 - **删除正文里已经说明的身份信息**description 只保留触发条件以及必要的 “when another skill needs...” 触达说明。 不要把 description 写成正文流程摘要。description 负责触发 skill不负责替代 SKILL.md。 ## Information hierarchy Skill 由两类内容构成**steps** 和 **reference**。它们可以自由组合一条 skill 可以全是 steps、全是 reference也可以两者都有。核心决策是使用哪类内容以及它们位于 **information hierarchy** 的哪一层。 信息层级按 Agent 多快需要这些材料排序 1. **In-skill step**写在 SKILL.md 里的有序动作是最高优先级。它告诉 Agent 按什么顺序做什么。每个 step 都应结束于 **completion criterion**即判断该步骤完成的条件。completion criterion 要尽量可检查必要时要穷尽。例如 “every modified model accounted for” 比 “produce a change list” 更强模糊标准会诱发 **premature completion**。 2. **In-skill reference**写在 SKILL.md 里的定义、规则或事实供 Agent 按需查阅。它可以是平铺的同级规则集例如 review skill 中每条规则都同等重要。平铺不一定是坏味道。writing-great-skills 本身就是全 reference 型 skill。 3. **External reference**从 SKILL.md 拆到单独文件里的参考内容通过 **context pointer** 触达只在 pointer 触发时加载。它可以是同目录下的 GLOSSARY.md也可以是 skill 系统外的普通参考文件。 强 completion criterion 会驱动更充分的 **legwork**。这不只适用于步骤型 skill即使是平铺 reference只要要求“每条规则都应用”也会驱动 Agent 做更多幕后工作。 放下去太少SKILL.md 顶部会臃肿放下去太多又会隐藏 Agent 实际需要的材料。这个张力就是 information hierarchy 的核心决策。 **Progressive disclosure** 是把 reference 沿层级往下移动从 SKILL.md 移到链接文件里让顶部保持清晰。机制上在 skill 目录里放一个命名明确的 .md 文件例如把完整术语定义放到 GLOSSARY.md。 一条 skill 可能有多种使用方式每种不同使用方式就是一个 **branch**。branch 是最干净的 disclosure 判断标准每条 branch 都需要的内容留在正文只有某些 branch 需要的内容放到 pointer 后面。**Context pointer** 的措辞而不是目标文件本身决定 Agent 什么时候以及多可靠地读取该材料。 如果 information hierarchy 决定一块内容放多深那么 **co-location** 决定它和谁放在一起一个概念的定义、规则和 caveats 应放在同一个标题下不要散落在文件各处。 ## When to split **Granularity** 是 skill 拆多细的问题。每次拆分都会花掉两种负载之一所以只有拆分收益明确时才拆。 有两种拆法 - **按 invocation 拆**当你有一个独立 **leading word** 应该触发某条 model-invoked skill或另一个 skill 必须能触达它时拆出一条 model-invoked skill。代价是新的 description 会常驻上下文增加 context load独立触达必须值得这个成本。 - **按 sequence 拆**当一个步骤后面的 **post-completion steps** 会诱导 Agent 匆忙结束当前步骤即发生 **premature completion**就把步骤序列拆开。让后续步骤不在当前上下文里可以促使 Agent 在当前任务上投入更多 **legwork**。 拆分不是为了形式上的模块化而是为了控制 context load、cognitive load 和 premature completion。 ## Pruning 每个含义都应该有一个 **single source of truth**只有一个权威位置。这样修改行为时只需要改一个地方。 逐行检查 **relevance**这一行是否仍然服务于这条 skill 要做的事 然后逐句猎杀 **no-ops**不要只按行检查。把每个句子单独拿出来做 no-op 测试它会改变模型相对于默认行为的表现吗如果不会删除整句而不是试图修饰它。要激进一点大多数 no-op prose 应该被删除不是被改写。 ## Leading words **Leading word** 是一个模型预训练中已经熟悉的紧凑概念Agent 在运行 skill 时会用它来思考。例如 _lesson_、_fog of war_、_tracer bullets_。它可以在很少 token 内编码一个行为原则因为它借用了模型已有先验。 leading word 通过重复出现积累分布式定义锚定一整片行为区域。它不一定必须重复很多次足够强的 leading word 可能出现一次就够。 它服务可预测性两次 - 在正文里它锚定 **execution**每次这个词出现Agent 都会回到同一类行为。 - 在 description 里它锚定 **invocation**当同一个词出现在用户提示、文档和代码库里Agent 更容易把这个共享语言和 skill 连接起来更可靠地触发 skill。 主动寻找能用 leading word 重构 skill 的地方。一个意思被三个句子反复解释或者 description 花一整句模糊指向某个概念通常都可以压缩成一个 token。 例子 - “fast, deterministic, low-overhead” 可以压成 _tight_例如 a _tight_ loop。 - “a loop you believe in” 可以压成 _red_把模糊门禁变成可观察的二值状态这个循环有没有在 bug 上变红 收益有两个更少 token以及更锋利的思考挂钩。假设每条 skill 都带着可以被 leading word 替代的重复说明然后去找它们。 ## Failure modes 用这些失败模式诊断用户在使用 skill 时遇到的问题。 - **Premature completion**当前步骤还没真正完成Agent 的注意力就滑向“已经完成”。防御顺序先锐化 completion criterion因为这是局部且便宜的修复只有当标准无法再清晰、且你确实观察到 rushing 时才通过拆分隐藏 post-completion steps。 - **Duplication**同一个含义出现在多个地方。它增加维护成本和 token 成本还会把这个含义在信息层级中的权重抬得过高。 - **Sediment**旧内容因为“添加安全、删除危险”而沉积下来。没有修剪纪律的 skill 默认都会出现 sediment。 - **Sprawl**skill 单纯太长即使每一行都还有效、也不重复。它损害可读性、可维护性并浪费 token。解决方法是使用 information hierarchy把 reference 放到 pointer 后面并按 branch 或 sequence 拆分让每条路径只携带需要的内容。 - **No-op**模型默认就会遵守的句子。你付出了 load却没有改变行为。测试方式是这句话会改变模型相对于默认行为的表现吗弱 leading word 也可能是 no-op例如当模型本来就会稍微认真时_be thorough_ 并不会增加多少约束修复方式是换成更强的词例如 _relentless_而不是换一种技术。2. 完整可复制中文 GLOSSARY.md术语文件下面是第二份核心文件也就是可直接复制为GLOSSARY.md的中文版本。它负责定义这条 skill 的术语边界和主文件一起才算完整。# Glossary好 Skill 的术语模型 什么样的 skill 才算好这里给出它的领域模型。skill 的目的是从随机系统中尽量拽出确定性下面每个术语都是作用在这个目标上的一个杠杆。这是 [writing-great-skills](SKILL.md) 所披露出来的参考文件。 任意定义里的 **加粗术语**也都在这个 glossary 中有自己的条目按标题查找即可。 ## Language ### Predictability可预测性 一条 skill 让 Agent 在每次运行时都以同一种 *方式* 行动的程度。这里的一致性指的是过程一致而不是输出一致。比如 brainstorming skill 应该“可预测地发散”每次 token 可以不同但行为模式应该稳定。它是其他所有术语共同服务的根目标成本和可维护性只是它的外在症状不是与它并列的竞争目标。 _Avoid_: consistency, reliability, robustness, output-determinism 这里的 _Avoid_ 不是“这些词绝对不能出现”而是“不要把它们当成 Predictability 的同义替代词”因为它们会把“过程稳定”误带成“系统可靠”或“输出确定”。后文类似。 ### Model-Invoked模型触发型 保留 **description** 字段的 skill。这样 Agent 能看见它并自主触发人也仍然可以手动输入它的名字所以 model-invocation 总是包含用户可达。不存在“只有模型能用、用户反而不能用”的状态description 只会增加 Agent 的发现能力不会减少人的触达能力。它用永久性的 **context load** 换来可发现性。它也可以被其他 skill 触达因为 description 让它对 Agent 可发现也就对 skill 可调用。一个内容全是 **reference** 的 model-invoked skill还可以作为共享参考的归宿多个 skill 需要的参考可以放在这一个可调用的地方。只有在 Agent 必须能自己想到这条 skill 时才选择 model-invocation如果它永远只会被手动调用就删除 description不支付 context load。 _Avoid_: ability, tool, capability ### User-Invoked用户触发型 去掉 **description** 的 skill。它对 Agent 不可见只能由人手动输入名称来触发。所以 user-invoked 是“只有用户能触达”而 **model-invoked** 是“用户和模型都能触达”。它用放弃 Agent 可发现性来换取零 **context load**。因为没有 description除了人之外没有东西能触达它其他 skill 也无法自动触发它。 _Avoid_: procedure, workflow, command ### Description skill 的机器可读触发器也是 **model-invoked** skill 被迫始终加载在上下文中的那个 **context pointer**。它的存在本身就是 invocation 轴保留它skill 就是 model-invoked删掉它skill 就是 **user-invoked**只能由人触达。它也是 model-invoked skill **context load** 的来源。 _Avoid_: frontmatter, summary ### Context Pointer 一种保留在 Agent 上下文里的指针它指向上下文外的材料并编码“什么时候该去读它”的条件。**Description** 是最上层的 context pointer从上下文窗口指向 skill指向披露文件的链接是同一种对象在下一层的表现。真正决定 Agent 什么时候去读、以及读得是否可靠的不是目标文件而是 pointer 的措辞。一个必须读取的材料如果被放在措辞很弱的 pointer 后面就是方差 bug先修 pointer 的写法只有在写法强化仍然无效时才把材料重新内联回正文。 _Avoid_: link, reference, import Context Pointer 强调的是“指向 触发条件 读取可靠性”而 link/reference/import 都只抓到其中一部分。 ### Context Load **Model-invoked** skill 对 Agent 上下文窗口施加的成本。它的 **description** 会在每一轮都被加载持续消耗 token 和注意力。**User-invoked** skill 正是通过没有 description 来逃避这种成本。它也是“是否继续拆成更多 model-invoked skills”的制动器。 _Avoid_: token cost, context bloat - token cost 说得太窄只讲数量 - context bloat 说得太偏结果只讲臃肿 - Context Load 讲的是 持续占用上下文窗口的整体负担token 注意力 ### Cognitive Load **User-invoked** skill 加在人身上的成本用户必须在脑中记住有哪些 skill、什么时候该用哪一个也就是“人自己当索引”。这正是 **model-invocation** 帮用户拿掉的负担也是“是否继续拆成更多 user-invoked skills”的制动器。它不是要被一味最小化的成本它本身就是人类能动性的价格。有些地方必须保留人的判断就应该花这笔 cognitive load不需要人的地方才应该尽量移除。 _Avoid_: human index, burden, overhead ### Granularity粒度 skill 拆得有多细。拆得越细就越会花掉两类负载中的一类更多 **model-invoked** skills 会增加 **context load**因为更多 description 会常驻上下文并争夺注意力更多 **user-invoked** skills 会增加 **cognitive load**因为用户要记住更多东西。拆分主要有两种依据。按 **invocation** 拆当你有一个清晰的 **leading word**并且你确实会在提示词里用它来触发 skill就可以把它拆成独立的 model-invoked skill。按 **sequence** 拆当一串 **steps** 里的某一步后续内容必须被隐藏时就应该拆开因为把它隔离进自己的上下文能让后面的东西暂时消失。也要小心反过来把多个 sequence 合并会让每个步骤都暴露在后续 **post-completion steps** 面前从而诱发 premature completion。 _Avoid_: chunking, modularity ### Router Skill 一种 **user-invoked** skill它的职责是指向其他 user-invoked skills列出它们是什么、什么时候该用哪个。这样用户只需要记住一个 skill而不是很多个。它只能提示不能真正触发那些 skill因为 user-invoked skills 没有 **description**除了人之外没人能触达它们。当 user-invoked skills 多到难记时router skill 就是解决 **cognitive load** 的办法。 _Avoid_: dispatcher, menu, registry, index, router procedure ### Information Hierarchy信息层级 skill 内容按“Agent 多快需要它”排序后形成的层级。它由两次切分共同决定内容是在文件内还是放到 pointer 后面内容是 step还是 reference。层级从上到下是 - **Steps**文件内主层 - 文件内的 **Reference**次层 - 被披露到 pointer 后面的 **Reference** 一条没有 **steps** 的 skill只使用下面两层而且这通常完全合理。例如 review skill 中的所有规则都可以平铺在同一层上这不是坏味道。信息层级和 invocation 是独立的一条 skill 无论是 model-invoked 还是 user-invoked都可以是全 steps、全 reference或两者兼有。真正有步骤的 skill如果把本该披露下去的 reference 留在文件内就会把 steps 埋住让 Agent 是否注意到它们变成掷硬币这不只是可读性问题而是方差来源。顶部必须保持清晰能往下推的内容就尽量推下去。 作用首先是保护注意力让Agent专注重要步骤其次是token 优化。 _Avoid_: structure, organization, layout ### Co-location共置 把 Agent 在同一时刻需要一起读的东西放在一起。比如一个概念的定义、规则和 caveats 放在同一个标题下而不是散落在不同段落里。它是 **Information Hierarchy** 在文件内部的配套原则hierarchy 决定一块内容放多深co-location 决定它和什么放在一起。reference 没有固定的唯一格式判断标准是这份 skill 读起来是否像一份写给 Agent 的文档。该放在一起的内容放在一起时它会更像分散时就不像。它和 **Duplication** 不同duplication 是同一个意思重复了两遍scattering 是同一个意思被拆散到很多地方。 _Avoid_: grouping, clustering, cohesion ### Branch skill 被调用的一种不同方式也就是它要处理的一个分支。不同 branch 会让 skill 在不同运行中走不同路径。一条带很多步骤的 skill 可能有很多 branch完全线性的 skill 则可能没有。 _Avoid_: path, case, fork ### Progressive Disclosure渐进披露 把 **reference** 沿着层级往下移动从 SKILL.md 挪到 **context pointer** 后面让顶部保持清晰。它首先不是一种 token 优化而是保护 **information hierarchy** 的办法。它的许可条件来自 **branching**只有部分 branch 需要的材料可以披露下去每条路径都需要的材料要留在正文里。如果某个必须读取的材料放在 pointer 后面却总是触发不稳先强化 pointer 的措辞只有失败后才把材料重新拉回正文。 _Avoid_: lazy loading, chunking ### Steps Agent 需要按顺序执行的动作。如果一条 skill 有 steps它们就是正文里的主层内容也是它真正值得放进 SKILL.md 的部分。不是所有 skill 都必须有 steps一条 skill 可以全是 steps如 tdd全是 **reference**如一条 review skill也可以两者兼有而这与 invocation 无关。每个 step 都会结束在一个 **completion criterion** 上无论这个 criterion 是清晰还是模糊。 _Avoid_: workflow, instructions, choreography ### Completion Criterion 告诉 Agent 一段工作何时算完成的条件也就是它判断 done 与 not-done 的依据。它有两个真正起作用的属性。第一是 **清晰度**Agent 能不能判断什么时候完成它用来抵抗 **premature completion**。模糊边界例如“理解到了”会让 Agent 很容易自认完成并滑到下一步这条作用只在存在 steps 时才成立因为 premature completion 是 steps 之间的失败。第二是 **要求强度**它要求 Agent 做多少 **legwork**。例如“每个修改过的 model 都交代清楚”会迫使 Agent 做扎实工作而“列出改动清单”就不会。这个维度不依赖 steps它也可以约束一组平铺的 reference因此一条没有 steps 的 skill 仍然可以有穷尽性要求例如“每条规则都应用”。最强的 completion criterion 同时具备可检查性和穷尽性。 _Avoid_: done condition, exit condition, stopping rule ### Post-Completion Steps 当前步骤之后还没开始的那些 **steps**。只要它们可见就会把 Agent 的注意力往前拉诱发 **premature completion**。看到的后续越多拉力越强防御方式是通过拆 sequence 把后续步骤藏起来。 _Avoid_: horizon, fog of war, lookahead ### Legwork Agent 在单个步骤内部做的幕后工作例如读文件、探索代码库、实际改代码、自己挖出需要的信息而不是把这些工作转嫁给用户。它存在于步骤结构之下不应该被单独写成 step而是隐含在措辞里由 Agent 主导而不是由 skill 直接编排。它是 **post-completion steps** 那种“跨步骤拉力”在步骤内部的对应物。它会被更强的 **leading word** 拉高也会被更强的 **completion criterion** 拉高包括那种作用在平铺 reference 上的穷尽性要求。它会变薄要么因为要求本来就弱要么因为 **premature completion** 提前把步骤截断了。 _Avoid_: scope, effort, diligence, coverage ### Reference Agent 按需查阅的材料定义、事实、参数、例子、条件指令等。如果 skill 有 **steps**reference 是次层如果没有 stepsreference 就是全部内容或者它甚至可以完全在 skill 系统外这就是 **External Reference**。reference 通过 **context pointers** 被触达也是 **progressive disclosure** 最该处理的对象。 _Avoid_: supporting material, docs, background ### External Reference 存在于 skill 系统之外的 **reference**一个普通文件没有 **description**没有 **steps**也不可被调用但任何 skill 都可以指向它。它适合承载那些不需要自己独立触发、但可能被多条 skill 共享的参考内容。对于两条 **user-invoked** skills 来说它也是唯一可共享的归宿因为它们彼此都没有 description不能互相调用。 _Avoid_: doc, resource, knowledge base ### Leading Word 一个紧凑的概念也可理解为 *Leitwort*。它最好已经存在于模型预训练中因此 Agent 在运行 skill 时能直接“借用”它来思考。例如 _lesson_、_proximal zone of development_、_fog of war_、_tracer bullets_。它用最少的 token 编码一个行为原则因为它调用了模型已有的先验。leading word 应该重复为“词”而不是重复为整句解释这样它会在全文中逐渐积累起分布式定义锚定一整片行为区域。你当然也可以自己造词只要定义得足够清楚但造词无法借用现成先验会把原本可以白拿的语义改成你必须自己付 token 去解释的成本所以优先选已有词。 leading word 会双重服务 **predictability**。在正文里它锚定 **execution**每次这个概念出现Agent 都更容易回到同一类行为即使在一堆平铺的 reference 里它也能把注意力聚焦到同一类检查点上。在 **description** 里它锚定 **invocation**而且不只是 skill 内部。当同一个词同时出现在你的 prompt、文档和代码库里Agent 更容易把这套共享语言和 skill 对上。description 最好也使用你平时真的会说出来的 leading words。 _Avoid_: keyword, term, motif ### Single Source of Truth 理想状态是每个含义都只有一个权威位置。这样你要修改 skill 行为时只改一处即可。**Duplication** 就是对这个状态的破坏。 _Avoid_: home, canonical location ### Relevance 一行内容是否仍然服务于这条 skill 要做的事。这是判断该保留什么的镜头。失去 relevance 有两种方式要么一开始就没真正服务任务只是多余解释或者是本该披露下去的 **branch**要么它曾经相关但后来过期了。skill 越短越容易保持 relevant因为每一行都更便宜复查。它和 **no-op** 不同relevance 判断的是“是否相关”不是“是否真的改变了行为”。 _Avoid_: load-bearing, staleness, freshness ## Failure Modes ### Premature Completion 当前步骤还没真正完成Agent 的注意力就已经滑向“尽快完成”。这是 steps 之间的失败没有 **steps** 的 skill 如果提前停下不叫 premature completion而叫在要求不足时出现的薄 **legwork**。它是两股力量的拉扯结果一边是可见的 **post-completion steps** 往前拉另一边是 **completion criterion** 的清晰度在往后稳住。模糊边界是必要条件一个锋利、可检查的边界可以抵抗后续拉力无论后面还暴露了多少步骤。所以防御顺序必须是**先锐化 completion criterion**因为这便宜而且局部只有当这个边界真的无法再清晰而且你也确实观察到 rushing 时才去 **隐藏后续步骤**。而隐藏只有跨越真实的上下文边界才有效例如交给一个 user-invoked hand-off 或 subagent内联的 model-invoked 调用不会让后续步骤真的消失。它是导致薄 legwork 的一种原因但两者并不等价就算一个步骤完整跑完legwork 也可能仍然很薄。 _Avoid_: premature closure, the rush, rushing, shortcutting ### Duplication 同一个含义有不止一个 **single source of truth**。它会增加维护成本因为你改一处就得改所有重复处也会增加 token 成本还会错误抬高这个含义在信息层级中的权重。它正好和 **leading word** 相反leading word 是为了有意提高一个概念的注意力而 duplication 是无意间把同一个意思写了两次。 _Avoid_: repetition, redundancy ### Sediment 旧内容像沉积层一样堆在 skill 里不再被清理。因为添加看起来安全删除看起来危险于是过时和不相关的内容一层层沉下来。没有修剪纪律的 skill默认都会走向 sediment。它是 **relevance** 被长期侵蚀后的状态而不是 **duplication** 那种简单的重复。 _Avoid_: accretion, bloat, cruft, rot ### Sprawl skill 单纯太长了。即使每一行都还活着、每一行都不重复它依然可能 sprawl。它会损害可读性因为 Agent 在行动前得先穿过更长的正文注意力也会被拉薄会损害可维护性因为每多一行就多一行要保持 **relevant**也会浪费 token。解决方法是用 **information hierarchy**把 **reference** 放到 **context pointers** 后面并按 **branch** 或 sequence 拆分让每条路径只携带它真正需要的内容。它不同于 **sediment**长度来自沉积和 **duplication**长度来自重复sprawl 是“长度本身”。 _Avoid_: bloat, length, size, verbosity ### No-Op 一条不会改变任何行为的指令因为模型默认就会这么做。你为它支付了 load却没有得到行为增量。判断方法是相对于默认行为这一行真的改变了什么吗一条内容可以完全 **relevant**却仍然是 no-op。让 **leading word** 能白嫖先验的同一套模型特性也让 no-op 变得毫无价值。 leading word 是一种 *技术*No-Op 是对一行内容的 *判决*两者会交叉。一个太弱的 leading word 也可能是 no-op例如当模型本来就已经“有点认真”时_be thorough_ 没有带来新的约束修复方式不是换技术而是换成更强、真正能通过 no-op 测试的词例如 _relentless_。所以 no-op 测试同时也是在检验 leading word 是否值得它那几次重复。它是模型相对的而不是读者相对的两个人如果争论一行是不是 no-op本质上是在争论“默认行为是什么”这要通过运行 skill 来验证而不是靠辩论。 _Avoid_: redundant instruction, restating the obvious, belaboring3. 后文只挑疑难点并加入主动回忆前面已经把完整中文SKILL.md和GLOSSARY.md放出来了所以后面不再贴完整原文也不逐节复述中文主文件已经说清楚的内容。这里的目标换成长期记忆每个难点都给出一个非平凡判断再给几个需要主动提取的回忆题。先自己答再回看上文。后文只处理这些容易读浅的点information hierarchy解决的不是排版而是注意力优先级leading word不是神秘开关而是可测试的语义压缩no-op怎么判断failure modes如何变成诊断框架4. Information hierarchy真正难的不是分类而是取舍表面上information hierarchy 只是把内容分成steps、in-skill reference、external reference。真正难的是判断当前最该让 Agent 先看到什么。它首先不是 token 优化。省 token 只是副作用。核心问题是如果SKILL.md顶部塞满暂时不需要的参考、定义、例子Agent 就更难稳定抓到当前该执行的主线。顶部材料的角色是保护注意力顺序。这也不等于专门防premature completion。两者有关但层级不同information hierarchy处理“什么材料先出现、什么材料后出现”premature completion处理“当前步骤为什么过早自认完成”后者常常需要先修completion criterion前者则是在安排材料位置避免步骤、参考、外部材料混成一团。快速回忆为什么说progressive disclosure不是首先为了省 token一条全 reference 的 skill 为什么仍然可以是好 skill如果一个必须读取的材料被放到 pointer 后面但 Agent 总是不读第一修复动作是什么答案要点因为它保护的是顶部注意力顺序不只是减少字数。因为有些 skill 的职责就是提供判断框架或规则集合不需要有序步骤。先强化 pointer 的措辞只有 pointer 变强仍失败才考虑重新内联。5. Leading word它是可测试的语义压缩不是模型内置开关leading word值得学但不能神化。它不是说每个模型内部都有一张公开词表写下某个词就必然触发固定行为。更稳妥的理解是某些词或短语在训练语料中携带了高密度实践语境因此有机会用更少 token 牵出更稳定的行为模式。它利用的是模型的分布式语义联想不是一个显式暴露的 API。所以leading word的判断标准不是“词看起来高级”而是它能不能真的压缩并稳定召回一个行为区域。几个例子lesson不是单纯“课程”而是一整套教学单元感fog of war不是修辞而是“故意隐藏后续信息防止提前行动”tracer bullets不是“先做 demo”而是“先打一条端到端可验证路径”red不是颜色而是 TDD 语境里“门槛是否真的失败”的二值状态leading word必须接受 no-op 测试。be thorough往往太弱因为模型默认就会有点认真relentless更可能改变行为因为它把过程拉向持续追问、不轻易停手。快速回忆leading word和普通 keyword 的差别是什么为什么自己造词通常比使用已有词更贵为什么be thorough可能是 no-op而relentless不一定是答案要点keyword 主要负责匹配leading word 试图压缩并召回一整片行为模式。造词不能借模型已有先验必须在正文里额外付 token 定义。be thorough接近模型默认行为relentless更具体地改变停止条件和追问强度。6. 怎么判断 no-opno-op的核心测试是删掉这句话以后模型行为会不会和默认行为有可观察差异如果答案是“基本不会”它就是 no-op。它可能相关、正确、听起来积极但仍然不改变行为。判断时不要问“这句话好不好”而要问四个更硬的问题默认行为测试没有这句话模型大概率也会这么做吗行为增量测试这句话新增了具体动作、顺序、证据、边界或完成条件吗违例可见性测试如果模型没遵守这句话能不能明确指出它违反了什么失败模式测试这句话到底在防哪一种默认失败如果说不出来通常很可疑。几个对照“请认真检查代码。”通常是 no-op。它没有定义认真到什么程度也没有给出可检查完成标准。“检查所有被修改的 model并说明每个 model 的行为是否受影响。”不是 no-op。它新增了对象范围、动作和完成条件。“使用最佳实践。”通常是 no-op。最佳实践没有领域边界也没有违例标准。“不要标记完成直到新增测试覆盖失败路径且本地测试通过。”不是 no-op。它改变了完成条件。快速回忆为什么“相关”不等于“不是 no-op”判断 no-op 时最重要的问题是什么leading word为什么也可能是 no-op答案要点一句话可以和任务相关但如果模型默认也会做它没有行为增量。删掉这句话以后行为是否有可观察差异。如果它太弱、太泛或只换了说法没有改变约束就仍然是 no-op。7. Failure modes术语最后要能变成诊断动作failure modes的价值不是背名字而是每个名字都对应一种修法。premature completion先锐化 completion criterion只有确实观察到 rush才考虑隐藏 post-completion stepsduplication合并到 single source of truthsediment删除过时沉积层sprawl重新安排 information hierarchy或按 branch / sequence 拆no-op删掉没行为增量的句子或换成更强的约束这里最值得抓的是no-op和leading word的交叉。原文不是说 leading word 总是好而是说leading word 也必须证明自己不是 no-op。这把词汇选择从审美问题拉回到行为问题。快速回忆哪个 failure mode 最容易由“只加不删”造成哪个 failure mode 最适合先检查 completion criterion哪个 failure mode 会让一个概念在文档里显得比它实际更重要答案要点sedimentpremature completionduplication8. 快速复习关键思想这一节不再重复文件结构而是用来做间隔复习。读完前面的完整SKILL.md、GLOSSARY.md和难点分析后应该能在不看上文的情况下提取出下面这些判断。关键思想压缩Skill 的目标不是让输出固定而是让过程更可预测。description不是摘要而是 model-invoked skill 的触发器。context load不只是 token 数量还包括注意力占用。information hierarchy不是排版技巧而是在保护 Agent 先看到当前最该看的材料。progressive disclosure首先不是 lazy loading而是把低频 reference 放到 pointer 后面维护顶部主线。completion criterion的强弱会直接影响legwork的厚度。leading word不是关键词而是可测试的语义压缩它也可能是 no-op。no-op的判断标准不是“这句话是否正确”而是“删掉以后行为是否有可观察差异”。failure modes不是术语列表而是诊断入口每个失败模式都应该对应一个修法。GLOSSARY.md不是附录而是术语边界文件它本身就是 progressive disclosure 的示范。快速回忆Predictability为什么不是output-determinismContext Pointer为什么不只是 linkContext Load比token cost多了哪一层含义Information hierarchy在保护什么什么内容应该留在SKILL.md什么内容可以放到GLOSSARY.md一个completion criterion怎样才算更强leading word和普通 keyword 的差别是什么怎么判断一句话是不是 no-oppremature completion为什么优先修 completion criterion而不是马上拆 skillduplication为什么会错误抬高一个概念的重要性答案要点Predictability是过程稳定不是结果一样。Context Pointer同时包含指向、触发条件和读取可靠性。Context Load还包含注意力竞争。它保护当前最该先被 Agent 看到的材料。高频原则和必须执行的步骤留在SKILL.md完整术语边界、低频参考、分支性材料可以放到 pointer 后面。更强的标准应该可检查、范围明确必要时穷尽覆盖。keyword 更偏匹配leading word 试图召回一整片行为模式。删掉它看模型行为是否仍然基本一样。因为模糊完成标准是 premature completion 的直接入口拆分是更重的修复。重复出现会让模型误以为这个概念在信息层级里权重更高。