writing-great-skills - SKILL-平芜编程栈

name: writing-great-skills
description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
disable-model-invocation: true
category: “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-authoring
workflow
coding-agents
tools:
claude-code
codex-cli
cursor

何时使用

当用户请求与此工作流匹配时使用：编写和编辑技能的良好参考——让技能可预测的词汇和原则。

_来源：mattpocock/skills（MIT）。_技能的存在是为了从随机系统中获取确定性。可预测性——代理每次运行采取相同的过程，而不是产生相同的输出——是根本美德；下面的每个杠杆都服务于它。

加粗术语在GLOSSARY.md中定义；在那里查找它们的完整含义。

调用

两个选择，付出不同的成本：

模型调用技能保留描述，因此代理可以自主触发它并且其他技能可以触达它（你也可以输入它的名字）。它贡献上下文负载——描述每轮对话都在窗口里。机制：省略disable-model-invocation，并编写面向模型的描述，带丰富的触发措辞（“当用户想要……、提到……时使用”）。
用户调用技能把描述从代理的触达范围中剥离：只有你输入它的名字才能调用它——也没有其他技能可以。零上下文负载，但它花费认知负载：你是必须记住它存在的索引。机制：设置disable-model-invocation: true；description变成面向人类的——一行摘要，触发列表剥离。

只有代理必须自行触达技能，或另一个技能必须触达它时，才选择模型调用。如果它只靠手动触发，就做成用户调用的，不付上下文负载。

当用户调用技能多到你记不住时，堆积的认知负载由路由器技能治愈：一个点名其他技能及各自使用时机的用户调用技能。

撰写描述

模型调用的描述做两件事——说明技能是什么，并列出应该触发它的分支。每个词都会增加上下文负载，所以描述比正文更需要狠剪：

前置技能的主导词——描述是它做调用工作的地方。
每个分支一个触发器。给单个分支改名的同义词是重复——"使用 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。解药是梯子：把参考公开到指针之后，并按分支或序列拆分，让每条路径只携带它需要的。
空操作—— 模型默认就已服从的行，所以你付负载说了一堆空话。检验标准：它相对默认改变行为吗？一个弱主导词（当代理已经比较彻底时要彻底）是空操作；修复是更强的词（不懈），而不是不同的技术。