# Writing Great Skills > 编写与编辑优秀技能的参考资料——让技能行为可预测的词汇与原则。 - Skill: `kscz0000/writing-great-skills` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add kscz0000/writing-great-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/writing-great-skills/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: kscz0000 (https://skillmd.com/u/kscz0000) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/kscz0000/writing-great-skills --- ## 适用场景 适用于此工作流匹配用户请求时：编写与编辑优秀技能的参考资料——让技能行为可预测的词汇与原则。 _来源：[mattpocock/skills](https://github.com/mattpocock/skills)（MIT）。_技能的存在，是从一个随机系统中榨取确定性。**可预测性**——让智能体每次运行都走相同的*流程*，而不是产出相同的输出——是根本的德性；下文中所有杠杆都为它服务。 **加粗术语**的定义见 [`GLOSSARY.md`](GLOSSARY.md)；请查阅该文件获取完整释义。 ## 调用方式 两种选择，各有取舍： - **模型调用**型技能保留**description**，因此智能体可以自主触发*并且*其他技能也能触达它（你仍然可以手动输入名称）。它会产生**上下文负载**——description 每轮都占据上下文窗口。机制：省略 `disable-model-invocation`，并撰写面向模型的 description，使用丰富的触发短语（如"当用户希望…、提及…"）。 - **用户调用**型技能从智能体的视野中移除 description：只有你手动输入名称时才能调用——其他技能也无法调用。零上下文负载，但会消耗**认知负载**：*你*必须记得它存在的索引。机制：设置 `disable-model-invocation: true`；此时 `description` 变为面向人的——一行概述，去掉触发词列表。 只有当智能体必须自主触达该技能、或另一技能需要触达它时，才选择模型调用。如果它仅由手动触发，就设为用户调用，免去上下文负载。 当用户调用型技能多到记不过来时，累积的认知负载要靠**路由技能**来化解：一个用户调用型技能，列出其他技能及各自的使用时机。 ## 编写 description 模型调用的**description**承担两项工作——说明技能是什么，以及列出应当触发它的**分支**。每个词都会增加**上下文负载**，因此 description 比正文更需要修剪： - **把技能的首词前置**——description 才是它完成调用工作的地方。 - **每个分支一条触发。**对同一分支的同义改写是**重复**——"使用 TDD 构建特性……要求测试优先开发"是一条分支写了两遍。合并它们；只保留真正不同的分支。 - **删去正文中已有的身份信息。**将 description 限定在触发条件，以及必要的"当另一技能需要…"可达条款。 ## 信息层级 一个技能由两种内容类型构成——**步骤**和**参考**——自由组合：可以是全步骤、全参考、或两者兼有。核心决策是使用哪种、以及各内容在**信息层级**上的位置，信息层级按智能体对内容的即时需求程度排序： 1. **技能内步骤**——`SKILL.md` 中有序的动作，主要层级：智能体要做的事情，按顺序。每一步以**完成标准**结尾——告诉智能体工作已结束的条件。让它*可校验*（智能体能区分完成与未完成吗？），并在重要的地方*穷尽*（"每个被修改的模型都已统计"，而非"产出变更清单"）——模糊的标准会招致**抢跑**。 2. **技能内参考**——`SKILL.md` 中的定义、规则或事实，按需查阅。通常是合理的扁平同级集合（一次审查的所有规则放同一层）——这是妥当的安排，不是异味。_本技能全是参考。_ 3. **外部参考**——从 `SKILL.md` 抽出到独立文件的参考，通过**上下文指针**触达，仅在指针命中时加载。（涵盖_已披露_参考——像 `GLOSSARY.md` 这样的同级文件，仍属于技能的一部分——以及完全**外部参考**，位于技能系统之外、任何技能都可指向它。） 要求严格的完成标准会驱动彻底的**实操**——智能体在工作内的挖掘——无论技能是否包含步骤，因为"每条规则都已应用"对扁平参考的约束力等同于"每步都已完成"对序列的约束力。 下沉得少，顶部臃肿；下沉得多，智能体真正需要的材料又被掩埋。那种张力就是全部的决策。 **渐进披露**是沿着层级向下——从 `SKILL.md` 进入链接文件——让顶部保持清晰。机制：在技能文件夹中放一个链接的 `.md` 文件，命名其内容（本技能将其完整定义披露到 `GLOSSARY.md`）。有些技能有多种用法，每种不同用法就是一个**分支**——不同运行沿不同路径穿过技能。分支是最清晰的披露测试：每个分支共同需要的内联，只有部分分支触达的推到指针之后。**上下文指针**的*措辞*，而非其目标，决定智能体何时以及多可靠地触达材料。 层级决定某块内容*下沉多远*；**就近放置**则决定一旦下沉*谁与它并列*：把一个概念的定义、规则、注意事项放在同一标题下，而非分散，让读到一处便顺带看到它的邻居。 ## 何时拆分 **粒度**是技能划分的精细度，每一次切割都消耗两种负载之一，因此只在收益成立时拆分。两种切割： - **按调用拆分**——当你拥有一个独立的**首词**应单独触发它、或另一技能必须触达它时，将一个**模型调用**型技能拆出。你为新的常驻**description**付出**上下文负载**，因此这种独立可达性必须值得。 - **按序列拆分**——当当前步骤后面的**步骤**（一步的**完成后续步骤**）诱使智能体抢完手头的（**抢跑**）时，拆出一段**步骤**序列。把它们藏出视野，让智能体在当前任务上做更多**实操**。 ## 修剪 让每个含义都只有一个**单一事实来源**：一处权威位置，修改行为只需一处编辑。 逐行检查**相关性**：它是否仍与技能所做的事相关？ 然后逐句查找**无效**指令，不只逐行：对每句话单独运行无效测试，未通过的就删整句，而非修剪字词。保持激进——大多数失败的散文应当删掉，而非重写。 ## 首词 **首词**是一个紧凑概念，已经存在于模型的预训练中，智能体在运行技能时用其思考（如_课题_、_战争迷雾_、_示踪弹_）。在文本中反复出现（不必一定出现——一个强首词也许只需一次），它累积分布式定义，并以最少的 token 把整片行为锚定到模型已持有的先验上。 它为可预测性服务两次。在正文中它锚定*执行*：智能体在每次该词出现时都触达相同的行为。在 description 中它锚定*调用*：当同一词存在于你的提示、文档、代码中，智能体把该共享语言关联到技能，更可靠地触发它。 寻找把技能重构为首词的机会。在三个位置展开的三联词（**重复**），花了整句描述一个概念的 description——每处都是乞求被**折叠**为单个 token 的段落。例如： - "快速、确定、低开销" -> _紧致_——一阶段中反复出现的一个品质——折成一个预训练词（_紧致_循环）。 - "你信得过的循环" -> _红_——把模糊门控转为二元可观察状态（循环在 bug 处变_红_，或不变）。 你双赢：更少的 token，*且*智能体挂靠其思考的钩子更锋利。假设每个技能都携带着首词可以退休的复述——去找它们。 ## 失败模式 用这些诊断用户可能遇到的技能问题。 - **抢跑**——在步骤真正完成前就结束，注意力滑向*已做完*。防御，按顺序：先锐化完成标准（廉价、本地）；仅当标准不可避免地模糊*且*你观察到抢跑时，通过拆分隐藏完成后续步骤（序列切割）。 - **重复**——同一含义出现在多于一处。增加维护成本和 token 数，并让该含义在层级上的权重超出其真实位置。 - **沉淀**——陈旧层累下而不清除，因为新增感觉安全、删除感觉冒险。这是任何不坚持修剪纪律的技能注定会走向的命运。 - **蔓延**——即便每行都在线且唯一，技能单纯地过长。损害可读性、可维护性，并浪费 token。解药是层级：通过指针披露**参考**，按**分支**或序列拆分，让每条路径只携带所需。 - **无效**——一条模型默认就遵守的指令，因此你付出负载却什么也没说。检验：相对默认它会改变行为吗？一个弱首词（在智能体已经差不多彻底时写_要彻底_）就是无效；解法是更强的词（_无情_），而非不同的技巧。 ## 局限 - 当工作流指定上游工具、账号、API key 或本地设置时需要相应的前置条件。 - 未经用户明确许可，不授权破坏性、生产环境、付费或对外消息类操作。 - 在将生成的产物或建议视为最终结论前，请用用户的真实来源进行验证。