| name | skill-hardening-from-incidents |
| description | Use when upgrading, hardening, or creating skills from reports, incident reviews, historical lessons, agent-team feedback, or repeated workflow failures |
| metadata | {"version":"1.0.0"} |
| user-invocable | true |
Skill Hardening From Incidents
概述
把报告、事故复盘和历史经验升级为 skill 时，目标不是复述事故，而是提炼 future-agent 能直接执行的规则。每条规则都必须来自证据、指向未来行为，并能通过 diff、路径扫描和主代理复核验证。
使用场景 / 不使用场景
使用场景：
- 用户要求根据报告、事故复盘、历史经验、Memorix 记忆或 agent team 反馈升级、加固或新建 skill。
- 事故已经有结论，需要把经验沉淀为后续 agent 可复用的流程、警戒项或验证清单。
- 发现多个 skill、根级 AI 记忆或对外分发文档之间存在规则漂移，需要统一修正。
不使用场景：
- 事故仍在排查，根因、修复方式或验证证据还没有定论。
- 用户只是要求修 bug、改实现、跑测试，而没有要求沉淀 skill 规则。
- 可以用脚本、测试或 schema 自动防住的问题；这类约束优先自动化，skill 只记录需要判断的部分。
先定写入目标
动手前先写下本轮允许写入的目标清单，并在执行中严格遵守：
- 项目局部 skill：写入
.agents/skills/<skill-name>/SKILL.md，适合仓库特有流程、路径约束、agent team 协作规则；新增或改名时同步根级 CLAUDE.md、AGENTS.md、GEMINI.md 技能表。
- 对外分发 skill：写入
ai-plugins/*/skills/<skill-name>/，内容必须站在安装后目录视角；不要写入本机绝对路径、开发期报告、monorepo 内部测试路径、CI 路径或仅本仓库可见的临时材料。命令示例使用安装目录内的相对路径，例如 scripts/sync.ts。
- 全局 skill：写入用户全局技能目录，适合跨项目通用规则；不要假设当前 monorepo 的目录、包名、脚本或私有约束存在。
- 根级 AI 记忆：只记录会影响整个仓库未来 agent 行为的规则；三份文档必须保持等价更新。
- Memorix：用于跨会话收口，记录决策链和完成状态；有可用 MCP 时优先使用项目作用域和稳定
topicKey。
如果写入目标、skill 类型或同步范围不明确，先问用户，不要用猜测扩大写集。
证据材料读取清单
不要只读二手总结。至少核对这些材料中与本次目标相关的部分：
- 用户给出的报告、事故复盘、历史经验、review 评论或 handoff。
- 当前要加固的
SKILL.md，包括 frontmatter、触发条件、常见错误、完成条件。
- 相关 diff：确认实际改了什么，而不是只相信子代理报告。
- 根级
CLAUDE.md、AGENTS.md、GEMINI.md 中的技能表和已有规则，避免重复或冲突。
- 相关 Memorix 记忆：查找同一事故、同类 skill、路径污染、发布或同步问题。
- 若涉及对外分发 skill，额外检查 README、CHANGELOG、plugin/marketplace 元数据和安装后路径假设。
证据不足时，只能记录待确认问题；不能把猜测写成规则。
提炼规则的方法
把事故材料压缩成 future-agent 规则时，按这个顺序写：
- 现象：未来 agent 会看到什么信号。
- 根因：真正导致错误的判断、路径、流程或角色问题。
- 错误诱因：agent 当时为什么会合理化错误做法。
- 未来规则：以后必须先做什么、禁止做什么、如何判断边界。
- 验证方式：用什么 diff、扫描、命令或人工复核证明规则被落实。
好的规则像操作约束：对外分发 skill 的示例路径必须以安装目录为基准。
坏的规则像流水账：某天某个 agent 在某次任务里忘记改 README，后来又补了两次。
agent team 闭环
涉及 agent team 时，至少分清三类角色：
- 主代理：界定目标写集、分配角色、合并结论；最终必须亲自查看 diff 和目标文件，不能只转述子代理报告。
- 编辑子代理：只在被授权文件内做小补丁，记录证据来源、未验证项和风险；不能重写大文件或顺手格式化无关文件。
- 验证子代理：独立检查最终文件、路径污染、frontmatter、触发条件、常见错误和 AI 记忆同步；输出可复核的检查点。
闭环要求：
- 开始前清理或忽略旧 agent team 的过期任务、旧 handoff、旧计划，避免把前一轮目标带入本轮。
- 每个子代理报告都必须落到文件 diff 或命令结果上。
- 主代理完成独立验证后，再把最终规则同步到 AI 记忆和 Memorix。
编辑准则
- description 只写触发条件，必须以
Use when... 开头；不要概括 workflow。
- skill 正文写可复用流程、判断标准和验证清单，不写本次会话流水账。
- 使用小补丁修改，避免重写整份大文件。
- 保持项目局部 skill、对外分发 skill、全局 skill 的边界清楚；局部经验不要误塞进对外分发 skill。
- 对外分发 skill 的示例、脚本、引用文件均以安装目录为基准，避免仓库源码视角污染用户安装后的使用体验。
- 同步根级 AI 记忆时，三份文档使用同一条目、同一措辞、同一插入位置。
验证清单
完成前逐项检查：
- 新增或修改的 skill 有 YAML frontmatter，至少包含
name、description；按项目要求补齐 metadata.version 和 user-invocable。
description 以 Use when... 开头，只描述触发条件，不写流程摘要。- 正文覆盖写入目标、证据读取、规则提炼、角色闭环、编辑准则、验证清单、常见错误和完成条件。
- 根级
CLAUDE.md、AGENTS.md、GEMINI.md 的技能表同步一致。
- 主代理查看实际 diff，而不是只信子代理总结。
- 对目标 skill 运行路径污染扫描；若是对外分发 skill，拒绝本机绝对路径、开发期报告、monorepo 内部测试/CI 路径。
- 有 Memorix MCP 时，存储本次决策链或完成状态，并 resolve 过期任务记忆。
路径污染扫描要按目标文件收窄执行，并把占位项替换为当前任务的风险模式：
rg -n "<本机绝对路径>|<用户目录>|<开发期报告目录>|<CI 工作流目录>|<内部测试目录>" <target-files>
扫描命中不一定都是错误；要按 skill 类型判断。对外分发 skill 的命中通常需要删除或改成安装目录相对描述。
常见错误
| 错误 | 修正 |
|---|
| 直接贴事故流水 | 改写成现象、根因、未来规则、验证方式 |
只改 SKILL.md 不同步 AI 记忆 | 新增或改名项目局部 skill 时，同步根级三份 AI 记忆文档 |
| 只信子代理报告不看 diff | 主代理必须亲自查看 diff、目标文件和关键命令输出 |
| 没清理旧 agent team | 开始前确认旧任务、旧 handoff、旧计划不会污染本轮目标 |
| description 写 workflow 摘要 | description 只写 Use when... 触发条件 |
| 把局部经验误塞进对外分发 skill | 局部规则写项目局部 skill 或根级 AI 记忆；对外分发 skill 只保留安装后用户可复用规则 |
| 对外分发 skill 暴露开发路径 | 改为安装目录相对路径，移除本机绝对路径、开发期报告、内部测试/CI 路径 |
| 完成后不收口 Memorix | 有 MCP 时存储决策链、文件变化和下一步，并 resolve 已完成任务 |
完成条件
- 目标写集与实际 diff 完全一致，没有无关文件修改。
- skill 内容是 future-agent 可执行流程，不是事故叙事。
- 三类 skill 边界清楚，尤其没有把本仓库路径假设泄露到对外分发 skill。
- 根级 AI 记忆和 Memorix 已按需同步。
- 主代理完成独立验证，并明确剩余风险或待人工确认项。
