self-learning

自我学习：将黄金路径沉淀为技能

这项技能会把你刚刚费了一番功夫才摸索出来的方法，转化为可复用的 Agent Skill，让你或队友在下一次会话中，无需从头摸索，就能直接沿着已验证的路径开始。

这是一项元技能：它不负责完成工作，而是记录工作是如何完成的。它与工具无关，适用于任何能读取 Agent Skills 格式的 Agent（例如原生加载 SKILL.md 技能的 Claude Code 和 Codex）。如果某一步因工具而异，会先给出通用版本，再将特定工具的细节作为示例。

识别时机

在日常工作中留意这些信号。任何一个信号都提示你可以将经验沉淀下来：

• 任务经历多次尝试、走了弯路或经用户纠正后才成功。成功的方法比周围那些失败的尝试更有价值。
• 你发现了Agent 事先不知道的项目特定信息：凭据或环境变量的位置、与某项服务通信的选择器或后端、不明显的命令、必要的操作顺序，或与直觉假设相悖的注意事项。
• 这是一个可能会重复执行的运维工作流：连接开发或生产数据库、部署、运行迁移、填充数据、在线验证更改、运行某个特定测试流程、轮换密钥、查看正确的日志。
• 用户明确提出：“记住这个”“把它保存为技能”“下次别让我再解释一遍”。

发现信号后立即行动——不要先征求许可，无论是用户提出的，还是你自己注意到的。将经验沉淀为技能，然后告诉用户你记录了什么以及保存位置（第 5 步）。用户随时可以编辑或删除它。

技能、记忆，还是跳过？

并非每条经验都值得单独建成技能——先分流，避免技能列表被一句话条目挤满：

• 多步骤、可复用的流程或工作流（如何部署、连接数据库、执行迁移流程、在线验证）→ 按照下面的流程将其沉淀为一项技能。
• 单条独立事实或一句话的纠正（环境变量名称、路径、一条注意事项）→ 如果你的运行环境提供轻量级记忆或笔记功能（例如 MEMORY.md 索引），就记录在那里；为了一句话创建完整技能有些小题大做。如果没有此类功能，就创建一项小型技能。
• 确实只会发生一次、很可能不会重现的事情 → 跳过。

沉淀经验时，也要记录失败的尝试，而不只是成功的方法：排除过哪些做法以及原因，往往比黄金路径本身更能为下一次会话节省时间。

晋升规则：不要把猜测奉为定论

技能具有权威性——下一次会话会直接信任它，而不会重新验证——因此晋升标准要高。只有在以下三项全部满足时，才编写技能：

1. 检查通过。 路径已实际验证——测试通过、命令正常退出、复现成功，或构建通过。记录具体通过了什么检查。“看起来能用”不算检查通过。
2. 明确的失败模式。 你能说清这条路径避免或诊断的失败（例如“构建缓存过期 → 出现虚假的类型错误”），而不是含糊地说“有时会出问题”。
3. 至少排除过一种行不通的方法。 你尝试过并排除了一种具体做法，也说明了原因。

如果缺少任何一项，它还不算技能——将其作为暂定备注留在记忆中（标记为未验证），或者直接跳过。这样可以避免把自信的猜测纳入技能集。

收获流程

• 1. 应用晋升规则（见上文）。通过检查 + 明确的失败模式 + 一个已排除的死胡同——否则就不算技能：记入记忆，或跳过。不要凭自信的猜测继续。
• 2. 选择范围并自行命名，使用下方的启发式规则——不要停下来询问。默认选择项目范围；起一个清晰、具体的 name。
• 3. 去重。 查找现有技能，选择更新而非重复创建。列出 Agent 的技能目录——项目级和用户级目录（例如，Claude Code 的 .claude/skills + ~/.claude/skills、Codex 的 .codex/skills + ~/.codex/skills，或你的工具对应的目录）。另外浏览一下记忆/笔记索引——其中已有的事实可能只需要添加一个指针。
• 4. 在委派前，从本次对话中提炼出黄金路径——趁记忆犹新，记录准确可用的命令、文件路径、环境变量名、必要顺序，以及同样重要的、需要避免的死胡同。这些是撰写技能的原始素材。
• 5. 委派撰写工作：如果你的工具支持，就交给继承本次对话上下文的子 Agent；否则就直接撰写——见下文。黄金路径只存在于本次对话中，因此撰写者必须掌握这些上下文。
• 6. 撰写完成后，将新技能的路径告知用户，并用一句话说明其中记录了什么。

范围：项目级还是全局级

• 项目级（仓库的技能目录，例如 .claude/skills/、.codex/skills/）：路径仅适用于此代码库——包括其环境变量、构建/发布步骤、架构和特殊情况。大多数从操作中总结出的技能都属于项目级，并通过 git 分享给团队。
• 全局级（用户级技能目录，例如 ~/.claude/skills/、~/.codex/skills/）：路径适用于多个项目——例如个人工具、跨仓库习惯，或与你的机器相关而非与某个仓库相关的工作流。

不确定时，优先选择项目级——过度共享的全局技能会在不适用其命令的仓库中触发。

委派编写工作（子 Agent 或内联处理）

编写技能的人需要了解本次对话的上下文——黄金路径只存在于这里。有两种同样有效的执行方式：

• 内联处理——在主循环中自行完成这些步骤。始终可行。
• 子 Agent——如果你的工具可以委派给会继承本次对话的子 Agent，就用它来把资料收集工作从主上下文中移出去。（Claude Code：使用 context: fork 的技能。Codex 和其他工具以各自的方式启动子 Agent。）不要交给没有上下文的全新 Agent——它会从空白状态开始，无从提取信息。

无论采用哪种方式，默认都会做得太多，所以要严格限定范围。按照以下说明（填入方括号中的内容）执行——交给子 Agent，或者由你自己内联完成：

你正在整理一项技能。你唯一的任务是编写一项新的 Agent Skill，记录我们刚刚在本次对话中总结出的黄金路径： [用一行描述此工作流]。

硬性规则：

• 只能在 [skills dir]/[skill-name]/ 下写入内容。不要修改项目源代码、运行构建、安装任何内容，也不要继续原始任务。
• 首先阅读 [this-skill-dir]/references/skill-authoring.md 和 [this-skill-dir]/assets/SKILL.template.md，然后按照其中的规范编写 SKILL.md，并根据流程需要添加 references/ 或 assets/ 文件。
• 记录流程——命令、路径、必要的顺序和注意事项，而不是一次性的答案。进行泛化，以便下次也能使用。
• 也要记录失败的尝试：哪些做法被排除，以及原因，让下次会话避开这些死路。将其放在 “What didn't work” 部分。
• 严格执行晋升规则：技能必须记录验证此路径的通过检查，指出它所应对的失败模式，并至少列出一个已排除的死路。如果缺少任何一项（例如，实际上并未验证），就停止并报告该技能不符合晋升条件——改为留下暂定的记忆记录，而不是编写技能。
• 绝不要写入秘密值（密码、令牌、连接字符串、API 密钥）。只记录在哪里可以找到它们：环境变量名称、选择器函数、MCP 工具或密钥管理器。将秘密复制到技能文件会造成泄露。
• 完成前进行自我验证（参见 skill-authoring.md 中的检查清单）。
• 回复时报告：写入文件的绝对路径，以及一行摘要。然后停止——不要继续处理原始任务。

注意事项

• 绝不要将机密写入技能文件。 技能会提交并开源。 指明机密存放的位置；绝不要复述其值。这是本技能中最重要的一条规则。
• 在调用 write_file 前的最后一刻，花 10 秒进行自检——在脑中用以下规则检查拟写入的内容：
  • 是否有任何一行包含字面值 Bearer 、Basic 、sk-、ghp_、 xox[bpars]-、AKIA，或长度达到 32 个字符及以上的 base64/十六进制字符串？→ 将其删去。
  • 是否包含连接字符串（postgres://、mysql://、mongodb://、 redis://、https://user:pass@、amqp://、kafka://）？→ 删除 凭据，保留 scheme、主机和路径。
  • 用户是否在对话早些时候粘贴过某个值，而你现在正要重新输入？→ 替换为来源指针（env:FOO_TOKEN、 ~/.aws/credentials、MCP 工具 secrets/get 等）。
  • 这个值是否是将由 hook 填入的占位符（YOUR_TOKEN_HERE、<api-key>、 ${TO_FILL}）？→ 仍然要删去；会被自动填入的占位符和字面值一样会泄漏。
  • 这是文档片段中的示例 URL 吗？→ 使用 example.com、 user:[email protected]，或文档中说明的测试 fixture。
• name 必须与目录名一致，且只能包含小写 a-z、数字 0-9 和连字符 — 不得以连字符开头、结尾或连续出现。名称不匹配会导致技能无法加载。
• 编写技能的人往往默认会越界（尤其是子 Agent）。 因此，上文的任务说明禁止触碰项目源代码或恢复原任务——将工作限制在技能目录内。
• 不要重复创建。 如果已存在近似相同的技能（或记忆），请更新它，而不是另建一个会与之竞争触发机会的技能。
• 记录流程，而不是答案。 “将 EMEA 的订单与客户关联”下次就毫无用处；“如何找到合适的表并构建查询”才是技能。请参阅 references/skill-authoring.md。
• 保持 SKILL.md 精简（少于 500 行、约 5000 个 token 以下）。将细节移至 references/，并告知读者何时加载各文件。

完整的编写规范请参阅 references/skill-authoring.md。填空模板见 assets/SKILL.template.md。