choosing-determinism

选择确定性

只要确定性可行，就始终选择确定性。模型步骤每次运行的结果都可能不同，每次运行都会消耗 token，而且无法测试；脚本则不会出现这些问题。

梳理每个步骤

通读整个技能：SKILL.md、其中的参考资料和脚本。对每个步骤都问：在输入相同的情况下，两次正确运行是否必须产生相同结果？如果是，就用脚本实现。

确定性：用脚本实现	判断：留给模型处理
获取、筛选、排序、计数或去重	在多个选项中做选择或权衡利弊
解析命令输出、文件或结构化数据	解读含糊的意图或文本
固定的命令序列，尤其是有顺序要求或会造成破坏的命令	编写或审查文本和代码
解析路径、名称、日期、年龄、版本或 ID	判断某项发现是否重要
检查格式、架构或前置条件	向用户解释结果
渲染人或解析器依赖精确布局的输出	起草措辞必须恰当的消息

拆分混合步骤：由脚本收集并规范化输入，由模型做出决定，再由脚本执行或呈现该决定。

优先顺序如下：在脚本中使用现有工具的结构化模式（如 --json 标志、查询筛选器或底层命令）；在技能的 scripts/ 中添加新脚本；最后才使用模型推理。

编写脚本

• 文件头注释应说明用法、参数、输出格式和每种退出码。
• 所有输入都通过参数或标准输入传入。绝不提示用户输入。只有当时钟、随机性或环境本身就是目标值时才读取它们，并接受覆盖值，以便测试固定这些值。
• 按定义的顺序输出 JSON 或固定格式的行，不附带文本说明。
• 明确报错：先检查所需工具，在标准错误中写明每个错误，并以非零状态退出。空输入或格式错误的输入绝不能返回成功。每个错误的末尾都要附上说明该问题的技能文件路径，并保留所封装工具自身的错误文本。
• 确保写入操作具有幂等性。使用合成输入进行测试，并覆盖每条错误路径。

将脚本接入 SKILL.md

写上“运行 scripts/<name> <args>”，然后说明如何处理每种输出和退出码。不要在说明文字中复述脚本的功能；文件头已对此作出说明。

无法保证确定性时

• 如果某个步骤看起来可以用脚本实现，但仍交由模型处理，请用一行说明原因，以免下一位编辑者尝试编写脚本。
• 不要伪造确定性：用关键词列表代替阅读代码，效果比让模型阅读代码更差，除非该列表就是作者的实际规则。

报告

列出移至脚本实现的每个步骤、每个新增或修改的脚本及其测试，以及每个看似可脚本化但仍交由模型处理的步骤和原因。