name: writing-great-skillsdescription: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.disable-model-invocation: truecategory: “skill-authoring”risk: “safe”source: “community”source_repo: “mattpocock/skills”source_type: “community”date_added: “2026-06-19”author: “Matt Pocock”license: “MIT”license_source: “https://github.com/mattpocock/skills/blob/main/LICENSE”tags:skill-authoringworkflowcoding-agentstools:claude-codecodex-clicursor何时使用当用户请求与此工作流匹配时使用编写和编辑技能的良好参考——让技能可预测的词汇和原则。_来源mattpocock/skillsMIT。_技能的存在是为了从随机系统中获取确定性。可预测性——代理每次运行采取相同的过程而不是产生相同的输出——是根本美德下面的每个杠杆都服务于它。加粗术语在GLOSSARY.md中定义在那里查找它们的完整含义。调用两个选择付出不同的成本模型调用技能保留描述因此代理可以自主触发它并且其他技能可以触达它你也可以输入它的名字。它贡献上下文负载——描述每轮对话都在窗口里。机制省略disable-model-invocation并编写面向模型的描述带丰富的触发措辞“当用户想要……、提到……时使用”。用户调用技能把描述从代理的触达范围中剥离只有你输入它的名字才能调用它——也没有其他技能可以。零上下文负载但它花费认知负载你是必须记住它存在的索引。机制设置disable-model-invocation: truedescription变成面向人类的——一行摘要触发列表剥离。只有代理必须自行触达技能或另一个技能必须触达它时才选择模型调用。如果它只靠手动触发就做成用户调用的不付上下文负载。当用户调用技能多到你记不住时堆积的认知负载由路由器技能治愈一个点名其他技能及各自使用时机的用户调用技能。撰写描述模型调用的描述做两件事——说明技能是什么并列出应该触发它的分支。每个词都会增加上下文负载所以描述比正文更需要狠剪前置技能的主导词——描述是它做调用工作的地方。每个分支一个触发器。给单个分支改名的同义词是重复——使用 TDD 构建功能……要求测试先行开发是一个分支写了两遍。合并它们只保留真正不同的分支。**剪掉正文已有的身份。**把描述限于触发器外加任何当其他技能需要……的触达条款。信息层级技能由两种内容类型构建——步骤和参考——它们自由混合技能可以全是步骤、全是参考或两者兼有。核心决策是用哪种以及每种在信息层级上的位置这是一个按代理需要材料的即时程度排序的梯子技能内步骤——SKILL.md中的有序动作主要层级代理做什么按顺序。每个步骤结束于一个完成标准即告诉代理工作已完成的条件。让它可检查代理能区分完成与未完成吗并在重要处穷尽“每个修改过的模型都说明”而不是生成变更列表——模糊的标准招致过早完成。技能内参考——SKILL.md中的定义、规则或事实按需查阅。通常是一个合法的扁平同级集一次审查的每条规则在同一梯级上——合理的安排不是问题。本技能全是参考。外部参考—— 从SKILL.md推到单独文件中的参考通过上下文指针触达仅在指针触发时加载。涵盖已公开的参考——同级的文件如GLOSSARY.md仍是技能的一部分——直到完全存在于技能系统之外、任何技能都可指向的外部参考。高要求的完成标准驱动彻底的深耕度——代理在工作中所做的挖掘——无论技能有没有步骤因为每条规则都应用约束扁平参考正如每个步骤都完成约束序列。往下推得太少顶部膨胀推得太多你隐藏了代理实际需要的材料。这种张力就是全部决策。渐进式公开是向下移动梯子——移出SKILL.md进入链接文件——以保持顶部可读。机制技能文件夹中一个链接的.md文件按它所容纳的内容命名本技能把完整定义公开到GLOSSARY.md。有些技能不止一种使用方式每种独特方式是一个分支——不同的运行走不同的路径。分支是最干净的公开检验内联每个分支都需要的内容只把部分分支触达的内容推到指针之后。上下文指针的措辞而非它的目标决定代理何时以及多可靠地触达材料。梯子决定一块内容往下多深共置决定一旦到了那里什么与它并排把概念的定义、规则和注意事项放在同一个标题下而不是分散这样读一部分就带来它的相邻部分。何时拆分粒度是你划分技能的精细程度每次切割花费两种负载之一所以只有在切割值得时才拆分。两个切口按调用—— 当你有一个应自行触发它的独特主导词或另一个技能必须触达它时拆分出一个模型调用技能。你为新的始终加载的描述付上下文负载所以那种独立触达必须值得。按序列—— 当尚在前面的步骤一个步骤的完成后续步骤引诱代理仓促完成眼前这一步过早完成时拆分一段步骤。让它们保持在视线之外鼓励代理在当前任务上做更多深耕度。修剪让每个含义保持单一事实来源一个权威位置这样改变行为就是一处编辑。逐行检查相关性它是否仍然与技能所做的事情相关然后逐句而不是逐行猎杀空操作对每个句子单独运行空操作检验当一个失败时删除整个句子而不是从它身上删词。要激进——大多数检验失败的散文应该删除而不是重写。主导词主导词是一个已存在于模型预训练中的紧凑概念代理在运行技能时用它思考例如lesson、fog of war、tracer bullets。在整个文本中重复虽然不必然——一个强主导词可能只需要一次它通过征集模型已持有的先验用最少的 token 累积一个分布式定义并锚定一整片行为。它两次服务于可预测性。在正文中它锚定执行每次词出现时代理都达到相同的行为。在描述中它锚定调用当同一个词存在于你的提示词、文档和代码中时代理把这种共享语言与技能关联起来并更可靠地触发它。猎取把技能重构为使用主导词的机会。在三个位置展开写出的三元组重复花一个句子暗示一个想法的描述——每一个都是渴望坍缩成单个 token 的段落。示例包括“fast, deterministic, low-overhead” -tight— 一个跨阶段重申的品质——坍缩成一个预训练的词一个tight循环。“a loop you believe in” -red— 把模糊的关卡转换为二元的可观察状态循环在 bug 上变red或者不变。你赢两次更少的 token和一个更锐利的钩子供代理挂它的思考。假设每个技能都携带着主导词可以退役的重述——去找它们。失败模式用这些来诊断用户可能遇到的技能问题。过早完成—— 在真正完成之前结束步骤注意力滑向已完成。防御按顺序先磨尖完成标准便宜、局部只有它不可约地模糊并且你观察到仓促时才通过拆分隐藏完成后续步骤序列切割。重复—— 同一含义在不止一个地方。带来维护和 token 成本并把含义在梯子上的显眼度抬过真实位次。沉积—— 因为添加感觉安全而删除感觉冒险而沉淀的陈旧层。任何没有修剪纪律的技能的默认命运。蔓延—— 技能就是太长即使每行都活跃且唯一。损害可读性和可维护性并浪费 token。解药是梯子把参考公开到指针之后并按分支或序列拆分让每条路径只携带它需要的。空操作—— 模型默认就已服从的行所以你付负载说了一堆空话。检验标准它相对默认改变行为吗一个弱主导词当代理已经比较彻底时要彻底是空操作修复是更强的词不懈而不是不同的技术。局限性当工作流指明上游工具、账户、API 密钥或本地设置时需要它们。未经用户明确批准不授权破坏性、生产、付费或外部消息操作。在把生成的工件或建议视为最终结果之前对照用户的真实来源进行验证。