run-history-skill-upgrader

运行历史技能升级器

语言策略

所有面向用户的输出均使用用户的语言。语言未知时，默认使用中文。

角色

将真实运行反馈转化为现有技能的结构性改进。升级可以新增、修改、合并、删除、弃用，也可以决定不做任何更改。

可移植性

此技能与 Agent 无关。在 Codex、Claude Code、OpenCode、OpenClaw、Hermes 及类似的本地 Agent 宿主中，只要能够读取 SKILL.md 以及可选的 references/、scripts/、evals/ 和 agents/，就应当可以使用。

• 从包含此 SKILL.md 的目录解析 <skill-dir>。
• <python> 表示宿主可用的 Python 启动器：python3、python 或 py -3。
• 不要假设固定的技能根目录、Shell、主目录布局或路径分隔符。
• <skill-dir>/scripts/... 之类的占位路径描述的是路径片段，不代表必须采用某种分隔符。在 Windows 上，使用 Shell 或测试框架接受的分隔符样式。
• 平台专用的辅助工具是可选的。只有在实际可用时才使用。

强制双阶段审批

此技能始终以 plan_only 开始。

1. plan_only：读取目标技能和已商定的证据范围，然后给出具体升级计划并停止。
2. apply_after_approval：只有在用户明确批准该计划后，才能修改文件。

以下表述本身不构成批准：

• “升级它”；
• “直接编辑它”；
• “别问我”；
• “继续”；
• 最初提出的改进技能请求。

有效批准必须明确指向当前计划，例如“批准计划 A”“执行上述计划”或“是的，执行该升级计划”。

工作流

1. 锁定目标技能的名称和路径。
2. 除非当前对话中已有明确的计划后批准，否则锁定为 plan_only。
3. 锁定证据范围：对话、日志、截图、工件、差异、测试、源文档或用户反馈。
4. 提出更改建议前，先阅读当前目标技能。
5. 对信号进行分类：流程缺口、验证缺口、来源漂移、平台漂移、用户偏好、候选想法、事件、路由缺口或内容冗余。
6. 设计案例集：事件、候选规则、回归案例、边界案例，以及可选的留出挑战。
7. 通过泛化门槛。单次事件不会自动成为应长期保留的规则。
8. 梳理路由影响。移除薄弱路由，并将可由机器检查的事实转移到工具、测试、模式检查、差异、验证器或文件中。
9. 选择净改进方案：no_change、maintenance_note_only、prune_or_consolidate、local_refactor、cross_reference_refactor、major_refactor 或 deprecate_or_replace_source。
10. 给出具体计划并停止。
11. 仅在获得明确批准后执行。
12. 验证并报告更改内容，同时记录后续风险。

证据规则

强证据：

• 用户反馈或更正；
• 真实运行输出、日志、截图、测试或差异；
• 目标技能的实际文件；
• 解释来源或平台漂移的官方文档或第一方代码库。

除非有其他证据佐证，否则以下属于弱证据：

• 单次超时；
• 一次页面加载失败；
• 未打开源页面的搜索摘要；
• 没有运行证据支持的模型生成想法；
• 被当作通用规则提出的私有路径或临时文件名。

升级规则

• 优先删除或合并过时的指导，而不是在其上不断叠加新提醒。
• 仅在示例能够保留复杂行为或重要故障恢复步骤时才保留。
• 临时用户偏好应仅在当前任务中生效，除非用户明确希望将其保留为持久行为。
• 留出挑战用于应用后的验证，不用于计划设计。
• 不要在发布的技能包中附带内部维护日志。如果目标技能已有维护日志，则只有在获得批准且用户希望在其中保留持久维护历史时才更新。

文件编辑规范

应用更改前：

• 阅读目标技能的 SKILL.md、相关 references/、scripts/、evals/ 和可选的 Agent 元数据；
• 保留与本次无关的用户更改；
• 在可行时，记录差异或快照引用；
• 只编辑属于当前已批准计划的文件。

不要将凭据、浏览器会话、私人账户数据、无关的个人路径或隐藏提示词写入目标技能。

验证

运行此升级器技能附带的验证器：

<python> <skill-dir>/scripts/validate_upgrade_artifacts.py --skill <skill-dir>

此验证器会检查软件包结构、可移植 Agent Skills 前置元数据字段集、引用路径、JSON 结构、Python 语法、常见的私人路径泄漏，以及升级器要求的批准条款。其免依赖的前置元数据预检支持标量字段、块文本和一层字符串元数据；遇到其他 YAML 形式时会拒绝处理，而不是自行猜测。特定宿主可能接受不同的语法或更窄的字段集，因此在该宿主上安装时，应以其规范验证器为准。结构检查既不会运行评估用例，也不能证明升级改善了行为。

然后运行目标技能自身的验证器和最小范围的相关技术检查：

• 对已修改的 Python 脚本运行 python -m py_compile；
• 对已编辑的 JSON 文件运行 python -m json.tool；
• 如果前置元数据中的 description 已更改，则运行触发回归测试；
• 如果工作流已更改，则运行路由和边界回归测试；
• 对高风险升级，将结果与原始失败案例、至少一个相似的正向案例，以及至少一个近似负向案例进行比较。

如果跳过验证或验证失败，不要声称升级已完成。

最终回复

报告：

• 目标技能及其路径；
• 结果是仅有计划，还是已应用；
• 实际使用的证据来源；
• 实际更改的文件；
• 实际运行的验证命令及其结果；
• 已删除或否决的想法及原因；
• 剩余风险或后续检查。

参考资料

• references/evidence-and-scope.md
• references/upgrade-decision-protocol.md
• references/validation-and-regression.md
• references/examples.md
• scripts/validate_upgrade_artifacts.py
• evals/evals.json