writing-great-skillslisted

# Writing Great Skills（编写优秀的 Skill） 一个 skill 的存在意义是从随机系统中规整出确定性。**predictability**——agent 每次运行采用相同的_过程_，而不是产生相同的输出——是根本美德；下面的每个杠杆都服务于它。 **加粗术语**在 [`GLOSSARY.md`](GLOSSARY.md) 中有定义；在那里查找完整含义。 ## Invocation（调用方式） 两个选择，权衡不同的成本： - **model-invoked** skill 保留**description**，所以 agent 可以自主 trigger 它，_而且_其他 skill 可以 invoke 它（你仍然可以手动输入它的名字）。它贡献于**context load**——description 每轮都在窗口中。机制：省略 `disable-model-invocation`，编写面向模型的 description，包含丰富的 trigger 短语（"当用户想要……、提到……时使用"）。 - **user-invoked** skill 从 agent 的可达范围中移除 description：只有你，输入它的名字，才能 invoke 它——而且没有其他 skill 能。零 context load，但它消耗**cognitive load**：_你_是必须记住它存在的索引。机制：设置 `disable-model-invocation: true`；`description` 变为面向人类——一行摘要，去掉 trigger 列表。 只有当 agent 必须能自行 invoke 该 skill，或其他 skill 必须 invoke 它时，才选择 model-invocation。如果它只通过手动 trigger，使其 user-invoked，不支付 context load。 当 user-invoked skills 多到你记不住时，积累的 cognitive load 由**router skill**治愈：一个 user-invoked skill，列出其他 skill 以及何时使用每个。 ## Writing the description（编写 description） model-invoked 的 **description** 做两件事——说明 skill 是什么，列出应该 trigger 它的**branch**。每个词增加**context load**，所以 description 的修剪比正文更需要严格： - **把 skill 的 leading word 放在最前面** —— description 是其 invocation 工作的地���。 - **每个 branch 一个 trigger。** 将单个 branch 重命名的同义词是**duplication**——"使用 TDD 构建功能……要求测试优先开发"是一个 branch 写了两遍。合并它们；只保留真正不同的 branch。 - **剪掉正文已包含的身份。** 保持 description 只包含 trigger，加上任何"当其他 skill 需要……"的可达子句。 ## Information hierarchy（信息层次） 一个 skill 由两种内容类型构建——**step**和**reference**——它们自由混合：一个 skill 可以全部是 step、全部是 reference、或两