craft-skills-and-memories

制作技能和记忆

一项技能，覆盖 Agent 指令来源生命周期的两端：创建值得保留的技能和记忆，并在它们在实践中失效时进行修复。

技能损坏或记忆过时都是 bug。绕过问题继续往下做，只会导致它在下一次会话中再次出现。

范围：

• 技能是通用的。 技能中的内容不应针对特定项目。只适用于某个项目的事实应放在该项目自己的文档或记忆中，而不是技能里。
• 记忆可以针对特定项目，也可以通用。 根据 Agent 的记忆系统所支持的范围（项目、用户或全局），在事实适用的范围内创建和修复记忆。

何时应用

创建：

• “将此保存为记忆” / “将此制作成技能” / “记住这一点”
• 决定将某个经验教训或工作流记录下来，以供今后的会话使用（决定如何回应纠正意见是 /never-twice 的职责，其第 3 级会将任务交接到这里）

修复：

• 技能中记录的标志、命令或文件已不存在
• 技能中的复制粘贴代码块会以可复现的方式出错
• 技能的提取或验证规则未能捕获预期内容
• 调用的记忆中提到了已不存在或已被取代的文件、标志或工作流
• 用户表示技能或记忆无法正常使用

质量标准（创建与修复皆适用）

• 以示例、场景或概念为主线，绝不以引述为主线。 具体实例（失败的命令、修正后的代码块、完整演示的场景）比抽象解释或用户原话更容易在未来会话中回想起来。
  • 每条内容都按实例优先的顺序组织：先说发生了什么、发生在哪里，再说它所体现的规则，最后说明适用边界或例外。
  • 只有当原话本身就是指令（禁令、命名规则）时，才保留简短的原文。否则，应将其改写成规则。
  • 修改以往以引述为主的条目时，将其改写为实例优先。
• 描述是触发条件：简短地以“在……时使用”说明它应该触发的唯一时机，绝不概述内容。写成摘要的描述会造成触发错误。
• 技能应包含可运行、可复制粘贴的代码块和完整示例，让从未接触过该内容的 Agent 也能照着执行。
• 技能清单应精简且互不重叠。 创建、合并和拆分技能时应遵循以下设计条件：
  • 每个触发时机都必须只有一个归属：技能要说明其适用的具体时机，清单中各技能的触发条件必须两两互斥。重叠就是缺陷，必须通过合并或细化来解决，绝不能容忍。此技能涵盖创建与修复的整个生命周期，正是这种合并：它们的触发时机归属同一处，面向同一读者。
  • 技能越少越好：面向同一读者、适用于同一时机的两个技能应合并。
  • 任何技能都不能过于复杂或庞大：技能变得臃肿时，应按触发时机拆分。即使触发条件重叠，复杂技能也绝不能吞并同级技能，应改为细化描述。
  • 全文应便于浏览：段落简短，重点前置，避免大段文字（内容顺序遵循上述实例优先规则）。可读性优先于风格规则，准确性规则始终优先。技能页面的正文或记忆正文应遵循 /working-text 技能；frontmatter 描述则应遵循此技能的触发条件要求。
  • 任何部分的形式都应随改动而定：除了达到此标准，不强制规定格式；绝不能同时用视觉元素和文字重复解释同一内容，保持程序员语体。下方 /natural-writing 条目会说明该技能适用于哪些正文内容。
  • 不考虑向后兼容性，包括文件夹：拆分、合并和退役都是正常改动，每次删除都必须按照 /never-twice 技能（删除防护）进行审查。托管仓库声明的兼容性约定（例如已发布的安装路径）仍约束该仓库中的文件夹移动。
• 记忆应记录原因，将相对日期转换为绝对日期，并链接相关记忆。无论存储形式如何（文件、记录或条目），每条记忆只记录一个事实，这样删除错误记忆时不会连带删除正确内容。错误的记忆应删除，而不是通过打补丁绕开。
• 重写正文时，如果 /natural-writing 技能存在且可调用，就应用该技能。如果你的运行环境只允许用户调用该技能，应建议用户运行 /natural-writing，而不是悄悄跳过这一步。

创建

1. 先检查是否已有合适的归属。 如果已有涵盖该主题的技能或记忆，就更新它。重复内容会逐渐产生差异。
2. 选择技能还是记忆。
   • 任何用户都可以安装的通用行为：技能。
   • 个人或项目相关事实、政策或偏好：记忆，范围应恰当。
   • 编码个人工作流而非可自动识别任务的技能，应仅允许显式调用。这意味着在 frontmatter 中设置 disable-model-invocation: true，并在 Codex 的 agents/openai.yaml 中设置 policy.allow_implicit_invocation: false。
3. 按照上述质量标准撰写，并以触发事件作为实例。
4. 接入工作流：技能应遵循其仓库的编写检查清单（清单文件、目录、检查）。如果记忆系统维护索引，则应在同一次编辑中为记忆添加索引条目。
5. 运行现有的质量检查（仓库检查、审查）。对于记忆，应重新阅读并自问：“一个全新的会话能否据此正确行动？”

修复

1. 排除暂时性原因

后端服务中断、沙盒限制和本地工具配置都不属于技能缺陷。只有根因在于指令本身的故障才算。

2. 先完成当前任务

绕过出问题的步骤，完成用户真正要求的任务。修复要随后进行，而不是取代任务本身。

3. 在权威源头修复

• 技能位于其创作仓库中：直接编辑受影响的源文件（SKILL.md、references/、scripts/）。
• 已安装或供应商提供的技能副本，且你获准编辑（例如个人技能目录）：编辑该副本。如果上游源仍存在缺陷，告知用户。
• 记忆：编辑记忆所在位置。如果记忆系统维护索引，则在同一次编辑中更新对应条目。记忆内容有误而非仅仅过时，应删除，而不是打补丁。
• 未获写入授权：向用户报告缺陷并说明建议的修复方案。

4. 融入修复，不要追加说明

重写受影响的步骤，使其本身准确并达到质量要求。确保复制粘贴的代码块可以运行。

在末尾附加一次性警告，会让原有的错误指令继续存在。删除规则的重写则须遵循 /never-twice 技能中的删除审查（删除防护规则）。

机械性故障优先修代码。 各类修复的落点如下：

• 技能中由脚本实现的机械性行为在实际使用中失败（探测误读、命令解析错误、边缘情况导致崩溃）：在脚本中修复，并添加能复现该问题的回归测试。
• 事件警示类文本是范围明确的例外：陷阱叙述和先验经验只保留在判断层面的经验教训中，因为机制由脚本实现。
• 公共契约文档（CLI 格式、架构、输出字段）则不同：它应与所描述的接口变更同步更新。如果漂移检查门禁会锁定文档与源代码，则由该门禁确保二者严格配套。
• 纯文档缺陷（激活元数据、调用示例、工作流说明）应在实际源文件中修复，绝不要为此修改并非故障原因的脚本。

为何优先修代码：将陷阱处理纳入经过测试的脚本后，就能防止它再次出现。若只把陷阱写进文档，警告目录会不断扩张：每次事件都会新增一段警告，文件越来越臃肿，而后续会话仍可能手动重写出错的步骤。

示例：某监控技能积累了关于 shell 探测的陷阱说明（拆分单词、grep 匹配自身、缺少 timeout 可执行文件），直到探测逻辑迁入经过测试的脚本，文档才精简为仅保留判断层面的内容。

5. 按照常规门禁流程提交修改

技能或记忆修改与其他变更一样：运行其所在位置规定的检查和审查流程。如果没有相关流程（例如普通的已安装副本），至少重新运行失败场景，确认重写后的指令能够正常工作。

操作示例

创建记忆。 用户两次纠正 Agent，要求将提交消息硬换行限制在 72 列。

• 这是记忆，不是技能：属于个人策略，适用于所有仓库，不是可安装的内容。
• 将其保存为用户级记忆 commit-message-rules，以这次纠正作为示例，并记录原因（如果记忆系统有索引，也要更新）。
• 以示例为主，而不是以引述为主：记录规则和具体的修改前后示例，而不是用户的原话。

技能缺陷。 按照一项审查技能操作时，claude -p --output-format stream-json 退出并报错，输出文件为空。

1. 是暂时性问题吗？不是：每次运行都会复现，而且 claude --help 显示 --output-format stream-json 需要 --verbose。根本原因是技能文档中的命令有误。
2. 添加 --verbose 后重新运行，完成审查。
3. 技能的权威源是其作者仓库的本地检出版本：编辑其中 SKILL.md 的复制粘贴代码块，将 --verbose 加进去。
4. 修复应直接写入代码块，使其按原样即可运行。不要添加“注意：还需传入 --verbose”之类的脚注。
5. 运行该仓库的检查，并将此编辑纳入同一变更集以供审查。

过时的记忆。 一条回忆起的项目记忆称，应通过 make release 部署，但 Makefile 几个月前已将目标重命名为 make publish。

1. 对照当前仓库核实：过时的是记忆，而不是构建流程。
2. 使用正确的目标完成部署。
3. 更新项目级记忆（如果记忆系统有索引，也更新其条目），将目标写为 make publish，并保留此次重命名作为具体示例。

不是缺陷。 同一命令因后端过载错误失败了一次，重试后成功。这是暂时性问题。完成任务，不要改动技能。

使用技能

每次调用都要判断是否适用。如果所调用技能的指南不适用于当前任务，请跳过整个技能或其中某条规则，并在作出决定时告诉用户原因。

• 绝不要机械地遵循技能，以致违背任务需要。
• 绝不要默默忽略技能。
• 用户设定的长期规则（例如提交门槛）仍然有效。这也适用于与当前工作确实冲突的指南。

报告

将创建了什么或发生了什么失败、根本原因，以及技能或记忆的变更情况，分别告知用户；这些内容应与原始任务的结果分开说明。