# Writing Great Skills > 用于编写和编辑高质量 Skill 的参考框架：通过调用设计、信息层级、引导词与剪枝提高执行过程的可预测性。 - Skill: `rollrollroll/writing-great-skills` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds add rollrollroll/writing-great-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/rollrollroll/writing-great-skills/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: RollRollRoll (https://skillmd.com/u/rollrollroll) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/rollrollroll/writing-great-skills --- # Writing Great Skills Skill 的价值是从随机系统中约束出**可预测性**：每次运行遵循相同过程，而不是产生相同输出。下面所有手段都服务于这一根原则。 正文中的**粗体术语**均在 [术语表](references/glossary.md) 中定义。需要判断概念边界或诊断失败模式时，读取对应条目。 ## 调用方式 在两种方式之间明确选择： - **模型调用型** Skill 保留模型可见的**描述**，让 agent 能自主触发，也让其他 Skill 能调用。代价是描述在每轮占用**上下文负载**。省略 `disable-model-invocation`，并在描述中写清真正不同的触发分支。 - **用户调用型** Skill 只由人类显式选择，模型和其他 Skill 都不能主动调用。它不占模型上下文，却增加用户必须记住它的**认知负载**。设置 `disable-model-invocation: true`，并把描述写成人类可读的一行摘要。 只有模型必须自主发现，或其他 Skill 必须调用时，才选择模型调用型。用户调用型数量多到难以记忆时，用一个用户调用型的**路由 Skill**列出各 Skill 的用途，而不是把它们全部改成模型调用型。 ## 编写描述 模型调用型 Skill 的描述同时说明“它是什么”和“哪些**分支**应触发它”。逐句压缩： - 把最能支配行为的**引导词**放在前面。 - 每个真实分支只保留一个触发条件；同一分支的同义改写属于**重复**。 - 删除正文已经承担的身份说明，只保留触发条件，以及其他 Skill 需要调用它时的可达性说明。 描述中的每个词都永久增加上下文负载，因此比正文更需要剪枝。 ## 信息层级 Skill 由**步骤**和**参考资料**组成，两者可以单独存在，也可以混合。按照 agent 需要信息的即时程度排列： 1. **Skill 内步骤**：`SKILL.md` 中按顺序执行的动作。每一步都以可检查的**完成判据**结束；需要穷尽时，判据要明确要求覆盖全部对象，防止**过早完成**。 2. **Skill 内参考资料**：运行时按需查询的定义、规则和事实。平级规则可以保持平铺，不必强造顺序。 3. **披露的参考资料**：移出 `SKILL.md`、通过**上下文指针**按条件加载的文件，或位于 Skill 外的**外部参考资料**。 把只服务部分分支的内容移到指针后，形成**渐进式披露**；所有分支都需要的内容保留在正文。指针的措辞决定 agent 何时读取目标，必读资料若经常漏读，先强化指针，再考虑移回正文。 层级决定信息放多深，**共置**决定同一层里哪些内容放在一起。让一个概念的定义、规则和例外相邻出现，避免读到半个概念。 ## 判断是否拆分 **粒度**越细，付出的负载越高。只在以下切分能改善可预测性时拆分： - **按调用拆分**：当新 Skill 有独立引导词、应被单独触发，或必须由其他 Skill 调用时，拆成模型调用型 Skill。独立可达性的价值必须足以抵偿新增上下文负载。 - **按顺序拆分**：当当前步骤的完成判据难以进一步锐化，而且观察到可见的**后续步骤**持续诱发过早完成时，用真正的上下文边界隐藏后续步骤。 先锐化完成判据；只有失败真实存在且判据仍不可避免地模糊时，才用拆分解决。 ## 剪枝 让每个行为含义只有一个**单一事实来源**。 逐行检查**相关性**：它现在是否仍影响 Skill 的目标行为？再逐句执行**无效指令**测试：如果删掉后模型默认仍会做同样的事，这句话就没有承担行为作用，应整句删除。 定期清除已经失效的**沉积**。如果每一行都仍然有效且唯一，但主体依旧难以阅读，就是**蔓延**；沿信息层级披露参考资料，或按分支和顺序拆分。 ## 使用引导词 **引导词**是模型预训练中已经存在、能以很少 token 激活一整片行为的概念，例如“苏格拉底式”“红灯”“迷雾”。优先选择已有概念；自造词需要额外定义，收益更低。 引导词同时提高两处可预测性： - 在正文中锚定执行，让 agent 每次看到它都调用相近的行为先验。 - 在描述中锚定调用；当用户提示、文档和代码也使用同一词时，Skill 更容易被正确触发。 寻找反复解释同一行为的段落，把它们压缩成一个足够强的引导词。每次压缩都必须通过无效指令测试：弱到不改变默认行为的词没有价值。 ## 诊断失败模式 - **过早完成**：步骤在真正达标前结束。先让完成判据变得清晰、可检查；只有判据本质上模糊且确实发生抢跑时，才隐藏后续步骤。 - **重复**：同一含义存在多个权威位置。合并为单一事实来源；引导词可以重复 token，但不要重复解释。 - **沉积**：旧规则因为只增不删而累积。用相关性检查移除失效层。 - **蔓延**：内容全部有效却仍然过长。用信息层级、分支或顺序切分降低单次加载量。 - **无效指令**：一句话没有改变模型默认行为。删除它，或换成真正能改变行为的强引导词。 - **否定式引导**：禁令把不希望出现的行为带进上下文。直接描述目标行为；确实需要硬约束时，同时给出要采取的正向动作。 完成一次编写或审查时，逐项应用上述原则，并确认每个保留的描述触发、步骤、参考资料和失败模式处理都有可解释的行为作用。