run-history-skill-builder

运行历史技能构建器

语言策略

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

角色

将真实运行历史转化为新的技能包、仅规划的技能设计，或在请求实际涉及现有技能时，提供升级交接材料。

可移植性

此技能与 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 或测试框架接受的分隔符样式。
• 写入文件前，先锁定输出目录。如果用户未提供目录，请提出一个中性的本地目标位置，例如当前仓库的 skills/ 目录或宿主 Agent 文档中指定的本地技能目录，然后等待确认。

工作流

1. 锁定意图：判断请求属于 plan_only、new_single_skill、router_skill、skill_suite 还是 existing_skill_upgrade_handoff。
2. 锁定证据范围：确认允许读取哪些对话轮次、文件、日志、产物、差异、浏览器流程或文字记录。
3. 写入文件前锁定输出位置。
4. 根据获准的证据还原工作流：用户目标、实际步骤、失败、修复、成功证明和审批关卡。
5. 仅在有助于更可靠地打包工作流时，借鉴本地或开源模式。
6. 将可复用的不变因素与局部偶发因素区分开，例如一次性的路径、账户名称、某天的产品异常或临时用户偏好。
7. 将工作流抽象为状态关卡、验证关卡、脚本、参考资料、示例和评测。删除依赖主观猜测的薄弱路径。
8. 选择能够保证正确性的最小化包。
9. 只有在满足前述关卡后，才编写技能。
10. 完成验证、报告剩余假设，并附上路径和检查结果交付技能包。

不要从“我看到了成功运行”直接跳到“我编写了技能”。中间缺失的环节决定了可移植性、隐私和泛化能力。

架构选择

• plan_only：用户需要经过审查的设计或审计，而不是文件。
• new_single_skill：一个稳定的工作流，或一个紧密关联的工作流系列。
• router_skill：一个入口，用于在多个现有技能或阶段之间进行路由。
• skill_suite：多个应同时发布、但分别触发的独立工作流。
• existing_skill_upgrade_handoff：实际任务是改进现有技能。请为 $run-history-skill-upgrader 编写清晰的交接材料，而不是在此处编辑该技能。

优先选择替换、合并和省略，避免包过度臃肿。

证据与范围

锁定意图后，默认允许使用：

• 当前可见对话；
• 用户提供的路径、产物、日志、屏幕截图和文字记录；
• 当前工作区文件、差异、测试和生成的输出；
• 为借鉴打包模式而查阅的类似公开技能或官方文档。

读取以下内容前，必须取得明确批准：

• 与当前任务无关的广泛本地会话存档；
• 浏览器 Cookie、本地存储、会话导出或账户缓存；
• 密码、令牌、API 密钥、验证码、多重身份验证数据或其他凭据；
• 已商定范围之外的无关私人文件夹或个人历史。

请将事实、推断和未解决的假设分开。绝不要将机密、隐藏提示词、私人账户标识符或无关个人数据写入发布的技能或其示例。

设计规则

• 让 SKILL.md 聚焦于触发边界、角色、工作流、安全门槛和参考资料导航。
• 将较长的分支专属指南放入 references/。
• 将确定性且重复的检查放入 scripts/。
• 如果工作流长期使用、风险高或容易过拟合，则将触发样例和回归样例放入 evals/。
• 仅在示例能体现复杂行为、故障恢复或边界条件时使用示例。每个示例都必须说明不变量和非目标。
• 由用户决定的事项仍由用户决定。可由机器检查的事实应交给脚本、测试、架构检查、差异检查、文件存在性检查或验证器处理。
• 除非用户或发布目标明确要求，否则不要创建每个技能专属的 README、安装脚本、变更日志或装饰性文件。
• 将 agents/openai.yaml 视为可选的 UI 增强，而非核心逻辑。

验证

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

<python> <skill-dir>/scripts/validate_skill_package.py <target-skill-dir>

此附带验证器会检查包结构、可移植的 Agent Skills frontmatter 字段集、引用路径、JSON 结构、Python 语法以及常见的私有路径泄漏。其无依赖项的 frontmatter 预检支持标量字段、块文本和一层字符串元数据；遇到其他 YAML 格式时会拒绝处理，而不会自行猜测。特定宿主可能接受不同的语法或范围更窄的字段集，因此在该宿主上安装时，应以其规范验证器为准。结构检查都不会运行 eval 用例，也不能证明技能能否正确触发或改善行为。

如果当前宿主提供规范的技能验证器，也要运行该验证器。在类似 Codex 的宿主上，这通常意味着运行平台技能工具中的 quick_validate.py 命令。

另外，运行最小范围的相关技术检查：

• 对修改过的 Python 脚本运行 python -m py_compile；
• 对编辑过的 JSON 文件运行 python -m json.tool；
• 使用最小且有效的集合进行触发审查，其中包括一个应触发用例、一个相近的应不触发用例和一个边界用例；只有在风险或不稳定性需要时才增加更多用例；
• 扫描私有绝对路径、凭据、隐藏提示词或特定环境残留。

如果跳过或未通过验证，不要声称已完成。说明存在的缺口和剩余风险。

最终回复

报告以下内容：

• 选择的包类型；
• 最终技能路径；
• 已创建或有意省略的文件；
• 实际使用的证据来源；
• 实际运行的验证命令及其结果；
• 仍需用户审核的假设；
• 结果属于 plan_only、新技能包还是升级器交接。

参考资料

• references/history-mining.md
• references/open-source-pattern-mining.md
• references/skill-design-protocol.md
• references/self-repair-and-evals.md
• references/examples.md
• scripts/validate_skill_package.py
• evals/evals.json