update-agent-learnings

此技能会更新持久化的 Agent 指引和实时 Agent 提示文件。

不可妥协的规则：

1. 只记录适合纳入 Agent 记忆的经验。
2. 保留一个中央经验真相来源；不要另行创建平行的中央文件。
3. 将已批准的经验同步到所有适用于受支持 CLI 的相关 Agent 界面。
4. 不要将“仅限 Claude Code”的经验传播到工程师/审查者 Agent 提示中。
5. 修改经验文件或任何 Agent 文件之前，必须先获得用户明确确认。

更新 Agent 经验

输入

• $request：可选的经验候选内容、范围提示、Agent 名称，或对本次会话所揭示内容的提醒

目标

在中央经验存储中添加一条经过验证的 Agent 经验，并将其同步到匹配的 Agent 文件，具体步骤如下：

• 确认该经验适合纳入 Agent 记忆
• 正确分类范围
• 更新一个规范的经验文件
• 重新生成相关的 ## Learnings 部分
• 将这些部分同步到所有现有的 Agent 界面

步骤 0：确认该经验适合纳入此处

此技能仅用于会影响 Agent 行为的持久化经验。

有效示例：

• 全局编码 Agent 规则，例如范围控制、测试或迭代
• 针对某种技术或角色的 Agent 专属规则
• 应保存在中央经验存储中、但不应推送到子 Agent 提示中的“仅限 Claude Code”经验

无效示例：

• 技能设计规则
• 主 CLAUDE.md 工作流规则
• 一次性实现说明
• 立即重写 Agent 提示的直接请求

加载 references/learning-scope.md，了解路由和范围分类。

如果该经验不适合纳入 Agent 记忆，请停止，并说明它应该放在哪里。

成功标准：明确确认该经验属于 Agent 经验系统。

步骤 1：提炼一条具体经验

回顾本次会话，找出最精炼且有用的规则。

将其分类为以下类别之一：

• Global
• Claude Code Only
• Agent-Specific

规则：

• 使用祈使语气撰写
• 优先选择一条精确的经验，避免模糊地堆砌规则
• 只有在确实适用于所有编码 Agent 时，才标记为 Global
• 对技能、编排、配置或项目设置相关的元工作，使用 Claude Code Only

成功标准：得到一条范围分类正确、可付诸行动的经验候选内容。

步骤 2：确定中央经验文件和 Agent 同步目标

找到规范的中央经验文件。

路径规则：

• 如果已有一个中央 Agent 经验文件，就使用该文件
• 如果 .agents/learnings/agent-learnings.md 和 .claude/learnings/agent-learnings.md 都存在，选定一个规范来源，不要手动维护两份
• 在此类 .agents 优先的代码库中，优先使用 .agents/learnings/agent-learnings.md
• 如果代码库中只有 .claude/learnings/agent-learnings.md，则使用该文件

然后查找 Agent 同步目标：

• 如果存在 .agents/agents/*/AGENT.md 目录树，则同步到其中
• 如果存在 .claude/agents/* 目录树，则同步到其中
• 如果两种目录树都存在，则将其视为实时 CLI 界面

加载：

• references/learning-scope.md，了解范围和重复项处理方式
• 仅当规范经验文件尚不存在时，才加载 references/agent-learnings-template.md
• references/agent-sync-contract.md，了解 Learnings 部分的生成与放置方式

成功标准：已确定规范经验文件和所有同步目标目录树。

步骤 3：向用户确认

编辑任何内容之前，向用户说明：

• 范围分类
• 最终措辞
• 规范经验文件
• 将要修改的同步目标

如需确认或调整措辞，请使用 AskUserQuestion。

在用户明确批准更新之前，不得写入任何内容。

成功标准：用户已批准该经验和同步范围。

步骤 4：更新中央经验文件

进行最小且正确的修改：

• 保留文件结构
• 将经验插入正确的章节
• 避免删除无关内容
• 仅当文件已有“Last updated”标记时才更新它

规则：

• 如果缺少规范经验文件，请根据 references/agent-learnings-template.md 创建
• 如果缺少相应章节，请创建最小兼容章节，不要重构整个文件
• 保持格式与现有文档一致

成功标准：中央经验文件中恰好包含一次已批准的经验。

步骤 5：重新生成并同步 Agent 文件中的 Learnings 章节

使用中央经验文件为每个目标 Agent 文件生成 ## Learnings 章节。

同步规则：

• 全局经验同步到所有编码／审查 Agent 文件
• 特定 Agent 的经验仅同步到相应 Agent 文件
• “Claude Code Only”经验保留在中央经验文件中，不推送到子 Agent 提示词
• 如果 Agent 文件已有 ## Learnings 章节，请完整替换该章节
• 如果没有，请按照 references/agent-sync-contract.md 中定义的位置插入该章节

重要提示：

• 如果 .agents 和 .claude Agent 目录树都存在，请同时更新两处
• 不要假设文件名一一对应；应确认实际存在的路径
• 同步经验时不要重写无关的提示词章节

成功标准：每个现存 CLI 目录树中的所有相关 Agent 文件都包含正确同步的 Learnings 章节。

步骤 6：验证并报告

验证：

• 经验在中央经验文件中恰好出现一次
• 同步目标已按预期更新
• Agent 的 Learnings 章节包含正确的全局及特定 Agent 内容
• “Claude Code Only”经验未泄漏到子 Agent 提示词中

报告：

• 范围分类
• 规范经验文件
• 已更新的同步目标目录树
• 最终措辞
• 是否创建或更新了文件

成功标准：用户可以清楚了解中央文件和各 Agent 界面中的具体变更。

防护措施

• 不要让模型主动调用此技能；此技能会修改持久化经验和 Agent 提示词文件。
• 不要添加 context: fork；此工作流会编辑当前代码库。
• 不要添加 paths:；这是通用维护技能。
• 不要在 SKILL.md 中内嵌路由矩阵、评分卡或冗长的 Learnings 示例。
• 未经用户明确批准，不要添加经验。
• 不要维护两个内容不同的中央经验文件。
• 如果 .agents 和 .claude Agent 界面都存在，不要遗漏任何一个 CLI 目录树。

何时加载参考文件

• references/learning-scope.md 用于判断经验是否应归入 Agent 记忆、选择合适的范围，以及处理重复内容。

• references/agent-learnings-template.md 仅在缺少规范中央经验文件、且必须创建最小兼容文件时使用。

• references/agent-sync-contract.md 用于在受支持的 CLI 目录树中生成 Learnings 章节，并将其放置在 Agent 文件中的正确位置。

输出约定

报告：

1. 经验是否获准，或是否被转至其他位置
2. 所选范围和规范经验文件
3. 最终批准的措辞
4. 更新了哪些 CLI Agent 目录树
5. 任何重复内容合并或同步目标的决策