update-skill-learnings

此技能会更新持久化的技能编写指南，必须严格遵守规范。

不可妥协的规则：

1. 仅记录关于技能结构、技能内容、反模式或单个技能设计的经验。
2. 拒绝记录应用代码和 Agent 行为方面的经验，并将其转交给正确的维护流程。
3. 只更新一个规范的经验文件，不要创建副本。
4. 写入前检查是否存在重复或近似内容。
5. 修改经验文件前，必须获得用户的明确确认。

更新技能经验

输入

• $request：可选的经验候选内容、技能名称、类别提示，或关于本次会话发现的提醒

目标

通过以下步骤，将一条经过验证的技能编写经验添加到中央经验库：

• 确认该经验适合记录在技能记忆中
• 选择正确的类别
• 更新规范的经验文件
• 保留文件结构并避免重复
• 准确说明具体变更内容

步骤 0：确认经验适合记录在此处

此技能仅用于持久化记录创建、审查或改进技能方面的指南。

有效示例：

• 有助于改进技能的结构模式
• 提高清晰度或易用性的内容模式
• 反复导致困惑的反模式
• 应集中记住的单个技能专属设计规则

无效示例：

• 应用实现规则
• 面向 Claude 主对话的 Agent 行为规则
• 现在就重写技能的直接请求
• 不值得长期保存的一次性说明

加载 references/learning-scope.md，了解内容路由、类别归属和失败模式。

如果该经验不属于技能经验系统，请停止操作，并说明它应转到何处。

成功标准：该经验明确属于持久化的技能编写指南。

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

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

规则：

• 优先选择一条明确的经验，而不是一长串含糊的观察
• 使用祈使语气
• 将其与具体模式、反模式或技能专属规则关联
• 避免记录已被更有力的现有指南所隐含的建议

合适的表述：

• “将冗长的检查清单放在参考资料中，而不是直接写在 SKILL.md 里。”
• “将持久记忆维护技能标记为 disable-model-invocation: true。”

不合适的表述：

• “技能应该更好。”
• “使用更清晰的指令。”

成功标准：你已得到一条可执行的经验候选内容，并有明确理由。

步骤 2：确定规范的经验文件并选择位置

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

路径规则：

• 如果仓库已有唯一的技能经验文件，则使用该文件
• 如果 .agents 和 .claude 版本同时存在，则更新规范的编写位置，不要创建第二个真实来源
• 在此规范的 .agents 目录树中，优先使用 .agents/learnings/skill-learnings.md
• 如果仓库仍仅使用 .claude/learnings/skill-learnings.md 作为经验存储，则使用该文件

选择正确的类别：

• Structural Patterns
• Content Patterns
• Anti-Patterns
• Skill-Specific Learnings

写入前：

• 搜索重复或近似内容
• 如果已有相似规则，则合并并调整措辞
• 让新增指令保持简短且适用范围明确

加载：

• references/learning-scope.md，了解内容路由、类别和重复项处理方式
• 仅当规范的经验文件尚不存在时，加载 references/skill-learnings-template.md

成功标准：已确定目标文件和所属章节，并已检查重复风险。

第 3 步：向用户确认

编辑经验记录文件之前，请先展示：

• 类别
• 最终措辞
• 目标文件
• 提取这条经验的原因

如需确认或润色措辞，请使用 AskUserQuestion。

在用户明确批准这条经验之前，不要写入。

成功标准：用户已批准这条经验、存放位置和目标文件。

第 4 步：更新经验记录文件

进行最小且正确的编辑：

• 保留文件结构
• 将这条经验插入选定的章节
• 避免删除无关内容
• 仅在文件已有“Last updated”标记时更新该标记

规则：

• 如果规范经验记录文件不存在，则根据 references/skill-learnings-template.md 创建
• 如果章节不存在，则创建最小兼容章节，而不是重构整个文件
• 保持格式与现有文档一致
• 不要在此工作流中同步或重写实际技能文件

成功标准：已批准的经验出现在规范经验记录文件的正确章节中。

第 5 步：验证并报告

验证：

• 这条经验恰好添加了一次
• 类别存放位置正确
• 文件结构仍然合理
• 更新内容没有偏离到应用代码或 Agent 行为方面

报告：

• 类别
• 目标文件
• 章节路径
• 最终措辞
• 文件是新建还是已更新

成功标准：用户可以准确看到持久化技能编写记忆发生了哪些变化。

防护规则

• 不要让模型主动调用此技能；它会修改持久化经验记录。
• 不要添加 context: fork；此工作流会编辑当前仓库。
• 不要添加 paths:；这是一个通用维护技能。
• 不要在 SKILL.md 中保留路由矩阵、质量评分表或冗长的失败案例目录。
• 未经用户明确批准，不要添加经验。
• 不要同时创建 .agents/learnings/skill-learnings.md 和 .claude/learnings/skill-learnings.md。
• 不要在此经验记录更新中重写实际技能文件。

何时加载参考资料

• references/learning-scope.md 用于判断这条经验是否属于技能记忆、选择正确类别、处理重复项，以及检查常见失败模式。

• references/skill-learnings-template.md 仅当规范中央经验记录文件不存在，且必须创建最小兼容文件时使用。

输出约定

报告：

1. 这条经验已获采纳，还是被转交到其他位置
2. 选定的类别和目标文件
3. 最终批准的措辞
4. 经验记录文件是新建还是已更新
5. 任何重复项合并或规范路径决策