writing-great-skills

name: writing-great-skillsdescription: 写作和编辑高质量 skill 的参考提供让 skill 行为更可预测的词汇和原则。disable-model-invocation: trueSkill 存在的目的是从随机系统中争取确定性。可预测性指 Agent 每次运行时采用同一种过程而不是产出同样的文本。下面所有杠杆都服务于这个目标。加粗术语的完整定义应放在GLOSSARY.md中当你不确定术语边界时先查术语表再修改 skill。Invocation先决定这条 skill 由谁触发。两种选择花费不同成本Model-invokedskill 保留description这样 Agent 可以自动触发它其他 skill 也可以触达它用户仍然可以手动点名。代价是context loaddescription 会在每轮对话里占用上下文窗口和注意力。机制上不设置disable-model-invocation并写面向模型的 description包含明确触发措辞例如 “Use when the user wants…” 或 “Use when the user mentions…”。User-invokedskill 对 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 descriptionmodel-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 hierarchySkill 由两类内容构成steps和reference。它们可以自由组合一条 skill 可以全是 steps、全是 reference也可以两者都有。核心决策是使用哪类内容以及它们位于information hierarchy的哪一层。信息层级按 Agent 多快需要这些材料排序In-skill step写在SKILL.md里的有序动作是最高优先级。它告诉 Agent 按什么顺序做什么。每个 step 都应结束于completion criterion即判断该步骤完成的条件。completion criterion 要尽量可检查必要时要穷尽。例如 “every modified model accounted for” 比 “produce a change list” 更强模糊标准会诱发premature completion。In-skill reference写在SKILL.md里的定义、规则或事实供 Agent 按需查阅。它可以是平铺的同级规则集例如 review skill 中每条规则都同等重要。平铺不一定是坏味道。writing-great-skills本身就是全 reference 型 skill。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 splitGranularity是 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 wordsLeading 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例如 atightloop。“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。Sprawlskill 单纯太长即使每一行都还有效、也不重复。它损害可读性、可维护性并浪费 token。解决方法是使用 information hierarchy把 reference 放到 pointer 后面并按 branch 或 sequence 拆分让每条路径只携带需要的内容。No-op模型默认就会遵守的句子。你付出了 load却没有改变行为。测试方式是这句话会改变模型相对于默认行为的表现吗弱 leading word 也可能是 no-op例如当模型本来就会稍微认真时be thorough并不会增加多少约束修复方式是换成更强的词例如relentless而不是换一种技术。Glossary好 Skill 的术语模型什么样的 skill 才算好这里给出它的领域模型。skill 的目的是从随机系统中尽量拽出确定性下面每个术语都是作用在这个目标上的一个杠杆。这是writing-great-skills所披露出来的参考文件。任意定义里的加粗术语也都在这个 glossary 中有自己的条目按标题查找即可。LanguagePredictability可预测性一条 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, capabilityUser-Invoked用户触发型去掉description的 skill。它对 Agent 不可见只能由人手动输入名称来触发。所以 user-invoked 是“只有用户能触达”而model-invoked是“用户和模型都能触达”。它用放弃 Agent 可发现性来换取零context load。因为没有 description除了人之外没有东西能触达它其他 skill 也无法自动触发它。Avoid: procedure, workflow, commandDescriptionskill 的机器可读触发器也是model-invokedskill 被迫始终加载在上下文中的那个context pointer。它的存在本身就是 invocation 轴保留它skill 就是 model-invoked删掉它skill 就是user-invoked只能由人触达。它也是 model-invoked skillcontext load的来源。Avoid: frontmatter, summaryContext Pointer一种保留在 Agent 上下文里的指针它指向上下文外的材料并编码“什么时候该去读它”的条件。Description是最上层的 context pointer从上下文窗口指向 skill指向披露文件的链接是同一种对象在下一层的表现。真正决定 Agent 什么时候去读、以及读得是否可靠的不是目标文件而是 pointer 的措辞。一个必须读取的材料如果被放在措辞很弱的 pointer 后面就是方差 bug先修 pointer 的写法只有在写法强化仍然无效时才把材料重新内联回正文。Avoid: link, reference, importContext Pointer 强调的是“指向 触发条件 读取可靠性”而 link/reference/import 都只抓到其中一部分。Context LoadModel-invokedskill 对 Agent 上下文窗口施加的成本。它的description会在每一轮都被加载持续消耗 token 和注意力。User-invokedskill 正是通过没有 description 来逃避这种成本。它也是“是否继续拆成更多 model-invoked skills”的制动器。Avoid: token cost, context bloattoken cost 说得太窄只讲数量context bloat 说得太偏结果只讲臃肿Context Load 讲的是 持续占用上下文窗口的整体负担token 注意力Cognitive LoadUser-invokedskill 加在人身上的成本用户必须在脑中记住有哪些 skill、什么时候该用哪一个也就是“人自己当索引”。这正是model-invocation帮用户拿掉的负担也是“是否继续拆成更多 user-invoked skills”的制动器。它不是要被一味最小化的成本它本身就是人类能动性的价格。有些地方必须保留人的判断就应该花这笔 cognitive load不需要人的地方才应该尽量移除。Avoid: human index, burden, overheadGranularity粒度skill 拆得有多细。拆得越细就越会花掉两类负载中的一类更多model-invokedskills 会增加context load因为更多 description 会常驻上下文并争夺注意力更多user-invokedskills 会增加cognitive load因为用户要记住更多东西。拆分主要有两种依据。按invocation拆当你有一个清晰的leading word并且你确实会在提示词里用它来触发 skill就可以把它拆成独立的 model-invoked skill。按sequence拆当一串steps里的某一步后续内容必须被隐藏时就应该拆开因为把它隔离进自己的上下文能让后面的东西暂时消失。也要小心反过来把多个 sequence 合并会让每个步骤都暴露在后续post-completion steps面前从而诱发 premature completion。Avoid: chunking, modularityRouter Skill一种user-invokedskill它的职责是指向其他 user-invoked skills列出它们是什么、什么时候该用哪个。这样用户只需要记住一个 skill而不是很多个。它只能提示不能真正触发那些 skill因为 user-invoked skills 没有description除了人之外没人能触达它们。当 user-invoked skills 多到难记时router skill 就是解决cognitive load的办法。Avoid: dispatcher, menu, registry, index, router procedureInformation 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, layoutCo-location共置把 Agent 在同一时刻需要一起读的东西放在一起。比如一个概念的定义、规则和 caveats 放在同一个标题下而不是散落在不同段落里。它是Information Hierarchy在文件内部的配套原则hierarchy 决定一块内容放多深co-location 决定它和什么放在一起。reference 没有固定的唯一格式判断标准是这份 skill 读起来是否像一份写给 Agent 的文档。该放在一起的内容放在一起时它会更像分散时就不像。它和Duplication不同duplication 是同一个意思重复了两遍scattering 是同一个意思被拆散到很多地方。Avoid: grouping, clustering, cohesionBranchskill 被调用的一种不同方式也就是它要处理的一个分支。不同 branch 会让 skill 在不同运行中走不同路径。一条带很多步骤的 skill 可能有很多 branch完全线性的 skill 则可能没有。Avoid: path, case, forkProgressive Disclosure渐进披露把reference沿着层级往下移动从SKILL.md挪到context pointer后面让顶部保持清晰。它首先不是一种 token 优化而是保护information hierarchy的办法。它的许可条件来自branching只有部分 branch 需要的材料可以披露下去每条路径都需要的材料要留在正文里。如果某个必须读取的材料放在 pointer 后面却总是触发不稳先强化 pointer 的措辞只有失败后才把材料重新拉回正文。Avoid: lazy loading, chunkingStepsAgent 需要按顺序执行的动作。如果一条 skill 有 steps它们就是正文里的主层内容也是它真正值得放进SKILL.md的部分。不是所有 skill 都必须有 steps一条 skill 可以全是 steps如tdd全是reference如一条 review skill也可以两者兼有而这与 invocation 无关。每个 step 都会结束在一个completion criterion上无论这个 criterion 是清晰还是模糊。Avoid: workflow, instructions, choreographyCompletion 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 rulePost-Completion Steps当前步骤之后还没开始的那些steps。只要它们可见就会把 Agent 的注意力往前拉诱发premature completion。看到的后续越多拉力越强防御方式是通过拆 sequence 把后续步骤藏起来。Avoid: horizon, fog of war, lookaheadLegworkAgent 在单个步骤内部做的幕后工作例如读文件、探索代码库、实际改代码、自己挖出需要的信息而不是把这些工作转嫁给用户。它存在于步骤结构之下不应该被单独写成 step而是隐含在措辞里由 Agent 主导而不是由 skill 直接编排。它是post-completion steps那种“跨步骤拉力”在步骤内部的对应物。它会被更强的leading word拉高也会被更强的completion criterion拉高包括那种作用在平铺 reference 上的穷尽性要求。它会变薄要么因为要求本来就弱要么因为premature completion提前把步骤截断了。Avoid: scope, effort, diligence, coverageReferenceAgent 按需查阅的材料定义、事实、参数、例子、条件指令等。如果 skill 有stepsreference 是次层如果没有 stepsreference 就是全部内容或者它甚至可以完全在 skill 系统外这就是External Reference。reference 通过context pointers被触达也是progressive disclosure最该处理的对象。Avoid: supporting material, docs, backgroundExternal Reference存在于 skill 系统之外的reference一个普通文件没有description没有steps也不可被调用但任何 skill 都可以指向它。它适合承载那些不需要自己独立触发、但可能被多条 skill 共享的参考内容。对于两条user-invokedskills 来说它也是唯一可共享的归宿因为它们彼此都没有 description不能互相调用。Avoid: doc, resource, knowledge baseLeading 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, motifSingle Source of Truth理想状态是每个含义都只有一个权威位置。这样你要修改 skill 行为时只改一处即可。Duplication就是对这个状态的破坏。Avoid: home, canonical locationRelevance一行内容是否仍然服务于这条 skill 要做的事。这是判断该保留什么的镜头。失去 relevance 有两种方式要么一开始就没真正服务任务只是多余解释或者是本该披露下去的branch要么它曾经相关但后来过期了。skill 越短越容易保持 relevant因为每一行都更便宜复查。它和no-op不同relevance 判断的是“是否相关”不是“是否真的改变了行为”。Avoid: load-bearing, staleness, freshnessFailure ModesPremature 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, shortcuttingDuplication同一个含义有不止一个single source of truth。它会增加维护成本因为你改一处就得改所有重复处也会增加 token 成本还会错误抬高这个含义在信息层级中的权重。它正好和leading word相反leading word 是为了有意提高一个概念的注意力而 duplication 是无意间把同一个意思写了两次。Avoid: repetition, redundancySediment旧内容像沉积层一样堆在 skill 里不再被清理。因为添加看起来安全删除看起来危险于是过时和不相关的内容一层层沉下来。没有修剪纪律的 skill默认都会走向 sediment。它是relevance被长期侵蚀后的状态而不是duplication那种简单的重复。Avoid: accretion, bloat, cruft, rotSprawlskill 单纯太长了。即使每一行都还活着、每一行都不重复它依然可能 sprawl。它会损害可读性因为 Agent 在行动前得先穿过更长的正文注意力也会被拉薄会损害可维护性因为每多一行就多一行要保持relevant也会浪费 token。解决方法是用information hierarchy把reference放到context pointers后面并按branch或 sequence 拆分让每条路径只携带它真正需要的内容。它不同于sediment长度来自沉积和duplication长度来自重复sprawl 是“长度本身”。Avoid: bloat, length, size, verbosityNo-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, belaboring