init-ai-md

init-ai-md 技能说明

本技能用于在项目中快速初始化和增量更新 AI 记忆文件。通过交互式选择和差异对比补全，帮助用户精确管理 AI 记忆文件内容。

核心功能

1. 初始化 AGENTS.md：检查并创建项目唯一的 AI 记忆文件
2. 交互式选择：扫描现有内容和可用模板，让用户选择需要的记忆项
3. 差异对比补全：深度对比文本差异，仅补全缺失内容而非全量替换
4. 旧模式迁移：将 legacy CLAUDE.md / GEMINI.md 内容恢复到 AGENTS.md，并把两个旧文件清空为重定向；迁移旧目录中的 record-bug-fix-memory
5. 技能表管理：扫描项目中 .agents/skills/ 目录下的现有技能，在 AGENTS.md 中创建并维护「本项目的技能表」章节
6. 内置技能初始化：支持将 record-bug-fix-memory 等内置技能模板部署到项目的 .agents/skills/ 目录中

唯一文档与旧模式处理

• AGENTS.md 是唯一事实来源；所有模板章节和技能表只写入该文件。

• 根目录存在的 CLAUDE.md、GEMINI.md 必须删除全部原有内容，只保留：

  请阅读本项目根目录内的 AGENTS.md 文档。@AGENTS.md
  

• 每次执行都删除 AGENTS.md 中「获取技术栈对应的上下文」二级章节及正文。

• record-bug-fix-memory 缺失时无条件安装；旧 .claude/skills 路径存在时迁移到 .agents/skills。

文档读取策略

• 第一次只读目录/标题结构（grep "^##" file）
• 根据任务需要，用 offset/limit 只读相关章节
• 更新文档时用 Edit 的精准替换，不要 Read 全文再 Write 全文

执行流程

步骤 1：检查 AGENTS.md 文件

1. 检查项目根目录是否存在 AGENTS.md、CLAUDE.md、GEMINI.md 文件
2. 如果 AGENTS.md 不存在：
   • 如果存在非空 CLAUDE.md 或 GEMINI.md，先将其内容迁移为新的 AGENTS.md
   • 如果两个 legacy 文件都存在且内容不同，使用 AskUserQuestion 让用户选择需要保留的内容
   • 如果三者都不存在或均为空，创建 AGENTS.md，并确保内容以中文编写
3. 如果 AGENTS.md 已存在：
   • 读取现有内容，准备进行扫描分析
4. 对根目录存在的 CLAUDE.md、GEMINI.md 删除全部原有内容，只保留：
   • 请阅读本项目根目录内的 AGENTS.md 文档。@AGENTS.md
5. 从 AGENTS.md 中删除「获取技术栈对应的上下文」二级章节及其正文

步骤 2：扫描分析

1. 扫描目标文件：

   • 提取 AGENTS.md 中所有的二级标题（## xxx）
   • 记录每个二级标题下的内容摘要
   • 建立现存记忆项清单

2. 扫描模板目录：

   • 读取 templates/ 目录下的所有模板文件名（不包含已删除的技术栈上下文模板）
   • 按照数字前缀顺序排序（如 01.xxx.md、02.xxx.md）
   • 提取每个模板文件内的二级标题
   • 建立可用记忆项清单

3. 对比分析：

   • 对比现存记忆项和可用记忆项
   • 识别三类情况：
     • 缺失：模板中有但目标文件中没有的记忆项
     • 需更新：标题相同但内容存在差异的记忆项
     • 已完整：内容完全一致的记忆项

步骤 3：交互选择

必须使用 AskUserQuestion 工具与用户交互：

1. 展示扫描结果：

   • 列出当前 AGENTS.md 中已存在的记忆项（二级标题列表）
   • 列出 templates 目录中可用的记忆项

2. 生成选择问题：

   • 使用 AskUserQuestion 工具的 multiSelect: true 模式
   • 将每个可用记忆项作为一个选项
   • 选项描述中标注该记忆项的当前状态：
     • [缺失] - 目标文件中不存在
     • [需更新] - 存在但内容不完整
     • [已完整] - 内容已完全一致
   • 默认推荐选中状态为[缺失]和[需更新]的记忆项

3. 询问示例：

   请选择需要处理的记忆项：
   
   选项：
   - 主动问询实施细节 [需更新] - 内容存在差异，将补全缺失部分
   - 编写测试用例规范 [缺失] - 将新增此记忆项
   - 报告编写规范 [已完整] - 内容一致，无需更新
   

4. 等待用户选择：

   • 用户可多选需要处理的记忆项
   • 用户可选择"其他"输入自定义需求

步骤 4：差异对比与增量补全

对用户选择的每个记忆项，执行精细的差异对比：

1. 逐行对比原则：

   • 深度阅读目标文件中该记忆项的完整内容
   • 深度阅读模板文件中该记忆项的完整内容
   • 逐行/逐段落进行对比

2. 识别差异类型：

   • 缺失行：模板中有但目标文件中没有的行
   • 缺失段落：模板中有但目标文件中没有的完整段落
   • 缺失子标题：模板中有但目标文件中没有的三级/四级标题及其内容
   • 内容差异：同一位置但文本不同（需谨慎处理，可能是用户自定义内容）

3. 增量补全策略：

   • 仅补全缺失内容，不全量替换
   • 保持目标文件中已有的自定义内容
   • 在合适的位置插入缺失的行/段落
   • 保持内容的逻辑顺序和层级结构

4. 示例：

   假设目标文件 AGENTS.md 存在以下内容：

   ## 编写测试用例规范
   
   测试文件使用 `*.test.ts`，放在项目的 tests 目录中。
   
   - 使用 `describe` 和 `test` 组织测试用例
   

   对应模板的内容：

   ## 编写测试用例规范
   
   测试文件使用 `*.test.ts`，放在项目的 tests 目录中。
   
   - 使用 `describe` 和 `test` 组织测试用例
   

   正确的处理方式：

   • 识别缺失内容：
     • 缺失列表项："- 使用 describe 和 test 组织测试用例"
   • 在原有内容的对应位置补全缺失项
   • 不要全量替换整个章节

5. 禁止事项：

   • 禁止使用任何形式的脚本进行批处理（Python、TypeScript、Shell 等）
   • 禁止一股脑复制粘贴整个模板内容
   • 禁止覆盖用户的自定义内容

手順 5：ローカルスキルを初期化またはアップグレードする

AGENTS.md の内容を更新した後、組み込みスキルのデプロイまたはアップグレードが必要か確認します。

1. スキルテンプレートディレクトリを確認する：

   • templates/record-bug-fix-memory/ ディレクトリを読み込み、組み込みスキルテンプレートが利用可能であることを確認します
   • テンプレートの template-version フィールドを読み込みます（現在は 2.0.0）

2. 旧形式の残存を検出する（移行の検出）：

   • プロジェクトに旧形式の .claude/skills/fix-bug/record-bug-fix-memory/SKILL.md が存在するか確認します
   • 旧形式が存在し、新しいパス .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md が存在しない場合：[旧形式を移行可能] とマークします
   • 移行操作の対象は record-bug-fix-memory のみです。その内容を .agents/skills/fix-bug/record-bug-fix-memory/ に移動し、古いスキルディレクトリを削除します
   • 新しいパスがすでに存在する場合は、.agents/skills/ を正規の場所とし、旧パスにしかない独立した事例を追加します。同名ファイルは上書きしません

3. プロジェクトに既存のスキルがあるか確認する（新形式）：

   • プロジェクトに .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md がすでに存在するか確認します
   • 存在しない場合（かつ移行可能な旧形式もない場合）：[デプロイ可能] とマークし、状況 A で無条件にデプロイします
   • すでに存在する場合は、frontmatter の template-version フィールドを読み込みます
     • バージョン番号がない、またはバージョンが 2.0.0 未満の場合：[アップグレードが必要] とマークします
     • バージョンが 2.0.0 以上の場合：[最新] とマークします

4. 旧バージョンの単層アーキテクチャかどうかを判断する：

   • [アップグレードが必要] とマークされた場合、既存の SKILL.md に大量のインシデント記録本文が埋め込まれているか確認します
   • 判断方法：### の第 3 レベル見出しの下に、10 行を超える内容ブロックがあるか検出します
   • 埋め込み事例がある場合：[アップグレードが必要 + 分割が必要] とマークします

5. デプロイまたはアップグレードを実行する：インストールや移行を行うかどうかを改めて尋ねません。状態は、以下の処理分岐を選択するためにのみ使用します。

   状況 A：新規デプロイ（[デプロイ可能]）

   • templates/record-bug-fix-memory/SKILL.md をプロジェクトの .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md にコピーします
   • 必要なディレクトリ構造を作成します
   • テンプレートの「事例インデックス」セクションは空の状態で開始し、プロジェクトでの蓄積に応じて段階的に追加します

   状況 B：スケルトンをアップグレードする（[アップグレードが必要]、埋め込み事例なし）

   • 既存の SKILL.md の該当セクションを、テンプレートの手順ガイダンス部分に置き換えます
   • プロジェクトに既存の事例インデックスがある場合は保持します
   • 同じディレクトリにある既存の独立した事例ファイルを保持します

   状況 C：アップグレード + 分割（[アップグレードが必要 + 分割が必要]）

   • SKILL.md に埋め込まれた各インシデント記録（### の第 3 レベル見出し + 本文）を抽出します
   • 各記録について、独立した事例ファイル YYYY-MM-DD-{slug}.md を作成します
     • 日付は見出しから取得します（見出しにない場合は現在の日付を使用します）
     • slug は見出しのキーワードから生成します
   • SKILL.md の「事例インデックス」セクションに、分割した各事例の要約インデックスを生成します
   • SKILL.md のスケルトンをテンプレートの手順ガイダンス部分に置き換えます
   • 最終的な SKILL.md には手順ガイダンスと要約インデックスのみを残し、インシデント本文は含めません

   状況 D：旧形式からの移行（[旧形式を移行可能]）

   • .claude/skills/fix-bug/record-bug-fix-memory/ の下に旧形式のスキルが存在することを検出します
   • プロジェクトでは .agents/skills/ をスキルディレクトリとして統一して使用します
   • .agents/skills/fix-bug/ ディレクトリを作成します（存在しない場合）
   • 旧スキルファイルと独立した事例を、すべて .agents/skills/fix-bug/record-bug-fix-memory/ に移動します
   • 移行済みの旧 record-bug-fix-memory ディレクトリを削除します。他の .claude/skills/ スキルは処理しません
   • 移行の完了後、新形式に従って手順 6 のスキルスキャンとスキル一覧の生成を再実行します
   • 注意：移行ではファイルの移動のみを行い、事例本文は変更しません。SKILL.md 内部のパス参照は各スキル側で管理します

   状況 E：最新（[最新]）

   • プロジェクトに既存のスキル本文、事例インデックス、独立した事例ファイルは置き換えません
   • 対象パスとバージョンフィールドのみを確認し、手順 6 に進みます

手順 6：「本プロジェクトのスキル一覧」を生成／更新する

手順 5 の完了後（新しいスキルをデプロイしたかどうかにかかわらず）、スキル一覧を生成または更新する必要があります。

1. プロジェクトのスキルをスキャンする：

   • プロジェクトの .agents/skills/ ディレクトリにあるすべての SKILL.md ファイルをスキャンします
   • .agents/skills/ が存在しない場合は、.claude/skills/（旧形式の残存）を確認します。旧形式が存在する場合は、先に手順 5 の移行操作を実行するようユーザーに提示します
   • 各スキルの name と description（YAML frontmatter から抽出）を読み込みます
   • 各スキルの相対パスを記録します

2. スキル一覧の内容を生成する：

   • templates/08.本项目的技能表.md の形式を参考にします
   • スキャンした各スキルについて、次の形式で項目を 1 つ生成します：

     - `{スキル名}`
       - パス：`{スキルの相対パス}`
       - 用途：{スキルの説明}
       - 起動タイミング：{スキル SKILL.md から抽出した使用場面}
       - 参考情報：{スキル SKILL.md から抽出した参考情報}
       - 制約：{スキル SKILL.md から抽出した境界上の制約}
     

   • record-bug-fix-memory の特別な処理：このスキルは二層ストレージアーキテクチャを採用しているため、スキル一覧の項目にはストレージアーキテクチャの説明と読み方のガイドを追加する必要があります。形式は次のとおりです：

     - `record-bug-fix-memory` — `.agents/skills/fix-bug/record-bug-fix-memory/SKILL.md` — バグ修正後の知見やインシデント記録の蓄積（デバッグ手順そのものではありません）。
       - **ストレージアーキテクチャ**：二層ストレージです。SKILL.md には手順ガイダンスと要約インデックスのみを記載し、詳細な事例は同じディレクトリ内の独立した `YYYY-MM-DD-{slug}.md` ファイルに保存します。
       - **読み方**：このスキルを使用する前に、まず SKILL.md を読んで手順を確認し、次に「事例インデックス」セクションに従って関連する独立した事例ファイルを必要に応じて読みます。
       - **書き込み方法**：新しい知見を追加する場合は、独立した事例ファイルを作成すると同時に、SKILL.md の「事例インデックス」に要約を追加します。インシデント本文全体を SKILL.md に記載することは禁止されています。
     

3. AGENTS.md に挿入または更新する：

   • AGENTS.md に「## 本プロジェクトのスキル一覧」セクションがすでにある場合：差分を比較し、新規または変更されたスキル項目のみを補完します
   • ない場合：スキル一覧のセクションを、AGENTS.md の第 1 レベル見出しの後、他の第 2 レベル見出しの前（つまり、ファイル冒頭のプロジェクト説明の直後）に挿入します

4. スキル一覧の配置要件：

   • スキル一覧は、他のすべての第 2 レベル見出しより前に配置する必要があります
   • これにより、agent が AGENTS.md を読む際に、利用可能なスキルの一覧を最初に確認できます

手順 7：古い AI メモリファイルを整理する

1. プロジェクトのルートディレクトリに CLAUDE.md または GEMINI.md ファイルが存在するか確認します
2. これらのファイルが存在する場合、既存の内容をすべて削除します（frontmatter、見出し、プロジェクトルールを含みます）
3. 次の内容のみを書き込みます：请阅读本项目根目录内的 AGENTS.md 文档。@AGENTS.md
4. 2 つのファイルを読み返し、内容が 1 字ずつ完全に一致することを確認します。この固定の移行操作についてユーザーに確認する必要はありません

テンプレートファイルの仕様

ディレクトリ構成

init-ai-md/
├── SKILL.md              # 技能说明文件
└── templates/            # 模板文件目录
    ├── 01.主动问询实施细节.md
    ├── 02.编写测试用例规范.md
    ├── 03.报告编写规范.md
    ├── 04.生成发版日志的操作规范.md
    ├── 05.沟通协作要求.md
    ├── 06.终端操作注意事项（防卡住）.md
    ├── 07.简单任务的高效执行原则.md
    ├── 08.本项目的技能表.md          # 技能表章节模板
    ├── 09.Karpathy Guidelines.md     # Karpathy 编码行为准则模板
    ├── 10.使用superpower技能的个人偏好.md
    ├── 11.文档读取策略.md
    └── record-bug-fix-memory/       # 内置技能模板
        └── SKILL.md                 # record-bug-fix-memory 技能模板

テンプレートファイルの命名規則

• 接頭辞：2 桁の数字（01-99）。挿入順を決定します
• 区切り文字：英語のピリオド . を使用します
• 名前：内容を表す中国語の名前
• 拡張子：.md

テンプレート内容の仕様

1. テンプレートファイルには第 2 レベルのディレクトリのみを含め、第 1 レベルのディレクトリは含めません
2. 1 つのテンプレートに複数の第 2 レベルのディレクトリを含めることができます
3. 第 2 レベルのディレクトリの見出しが、挿入後のセクション見出しになります
4. 内容は簡体字中国語で記述します

内置技能模板规范

templates/ 目录下除了序号前缀的记忆项模板外，还可以包含子目录形式的内置技能模板：

1. 内置技能模板以独立子目录存放（如 templates/record-bug-fix-memory/）
2. 每个内置技能模板目录中必须包含 SKILL.md 文件
3. 内置技能模板的 SKILL.md 遵循 Claude Code Skills 的 YAML frontmatter 规范
4. 内置技能模板中不应包含项目特有的内容（如具体的仓库级事故记录），这些内容应在部署后由项目积累
5. 内置技能模板部署到项目时，目标路径为 .agents/skills/{类别}/{技能名}/SKILL.md

执行示例

场景 1：全新项目初始化

用户：请帮我初始化 AI 记忆文件

执行流程：

1. 检测到无 AGENTS.md → 创建 AGENTS.md
2. 扫描 templates/ 目录，建立可用记忆项清单
3. 使用 AskUserQuestion 询问用户需要哪些记忆项
4. 用户选择后，按序号顺序插入选中的模板内容
5. 确认 AGENTS.md 已创建，继续执行技能检查和技能表生成

场景 2：增量更新现有项目

用户：请更新我的 AGENTS.md 记忆文件

执行流程：

1. 检测到已有 AGENTS.md → 读取现有内容
2. 扫描现有二级标题，建立现存记忆项清单
3. 扫描 templates/ 目录，建立可用记忆项清单
4. 对比分析，标注每个记忆项的状态（缺失/需更新/已完整）
5. 使用 AskUserQuestion 询问用户需要处理哪些记忆项
6. 用户选择后，对每个选中项执行差异对比和增量补全
7. 检测到存在 CLAUDE.md/GEMINI.md → 删除旧内容并写入固定重定向
8. 回读 AGENTS.md 与重定向文件，完成验收

场景 3：差异对比补全示例

用户：更新 AGENTS.md 中的"编写测试用例规范"章节

执行流程：

1. 读取 AGENTS.md 中该章节的完整内容
2. 读取对应的记忆项模板内容
3. 逐行对比，发现：
   - 缺失描述段落
   - 缺失测试文件格式或断言规范
4. 在对应位置补全缺失内容
5. 保持原有的自定义内容不变

场景 4：初始化本地技能并生成技能表

用户：请帮我初始化 AI 记忆文件

执行流程：

1. 检测到无 AGENTS.md → 创建 AGENTS.md
2. 扫描 templates/ 目录，建立可用记忆项清单
3. 使用 AskUserQuestion 询问用户需要哪些记忆项
4. 用户选择后，按序号顺序插入选中的模板内容
5. 检查 .agents/skills/ → 不存在 record-bug-fix-memory
6. 无条件创建 .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md
7. 扫描 .agents/skills/ 全部技能 → 生成「本项目的技能表」章节
8. 将技能表插入 AGENTS.md 的开头位置（一级标题之后、其他二级标题之前）
9. 对存在的 CLAUDE.md/GEMINI.md 写入固定重定向并完成验收

场景 5：增量更新时发现新技能

用户：请更新我的 AGENTS.md 记忆文件

执行流程：

1. 检测到已有 AGENTS.md → 读取现有内容
2. 扫描 templates/ 和已有记忆项 → 对比分析
3. 用户选择更新记忆项 → 执行差异补全
4. 检查 .agents/skills/ → 发现已有 record-bug-fix-memory
5. 扫描 .agents/skills/ → 发现用户新增了 code-style 技能
6. 对比现有技能表 → 识别新增技能
7. 补全技能表，新增 code-style 条目
8. 检测到存在 CLAUDE.md/GEMINI.md → 删除旧内容并写入固定重定向

技能表管理详细说明

技能表的作用

「本项目的技能表」章节的作用是让 agent 在读取 AGENTS.md 时，能够快速了解项目中可用的技能清单，包括：

• 技能名称和路径
• 技能的用途和触发时机
• 技能的参考作用和约束

这帮助 agent 在合适的场景下主动调用正确的技能，而不需要逐个扫描 .agents/skills/ 目录。

技能表条目格式

每个技能条目遵循以下格式（参考 templates/08.本项目的技能表.md）：

- `{技能名称}`
  - 路径：`.agents/skills/{类别}/{技能名}/SKILL.md`
  - 用途：{技能描述，从 YAML frontmatter 的 description 字段提取}
  - 触发时机：{从 SKILL.md 的"何时使用"章节提取关键触发条件}
  - 参考作用：{技能的辅助参考价值}
  - 约束：{技能的边界限制}

技能表更新策略

1. 新增技能时：扫描发现新的 SKILL.md → 在技能表末尾追加条目
2. 技能变更时：检测到技能描述或路径变化 → 更新对应条目
3. 技能删除时：扫描未发现已记录的技能 → 使用 AskUserQuestion 询问用户是否移除该条目

内置技能部署详细说明

record-bug-fix-memory 技能

这是一个专用于 bug 修复经验沉淀的技能，采用双层存储架构。部署后：

1. 目标路径：.agents/skills/fix-bug/record-bug-fix-memory/SKILL.md
2. 来源模板：templates/record-bug-fix-memory/SKILL.md（template-version: 2.0.0）
3. 双层存储架构：
   • SKILL.md：只放流程指导 + 案例摘要索引（保持精简）
   • 独立案例文件：每条详细事故记录写成 YYYY-MM-DD-{slug}.md，与 SKILL.md 同目录
   • 禁止将完整事故记录正文内嵌到 SKILL.md 中
4. 部署后状态：
   • 技能的通用框架已就绪（概述、何时使用、记录流程、案例文件规范等）
   • 「案例索引」章节为空，等待项目实际积累
   • agent 可以立即使用该技能记录 bug 修复经验
5. 持续演进：
   • 每次 bug 修复后，agent 创建独立案例文件 YYYY-MM-DD-{slug}.md
   • 同时在 SKILL.md 的「案例索引」章节追加一条摘要索引
   • 这使得技能随项目使用逐步丰富，同时 SKILL.md 保持精简可读

部署注意事项

• 全新部署：如果目标路径不存在，创建目录结构并部署模板
• 升级部署：如果已存在旧版（无 template-version 或 < 2.0.0），执行升级流程（见步骤 5）
• 不会覆盖案例：升级时保留项目已有的独立案例文件
• 技能表同步：部署完成后自动更新 AGENTS.md 中的技能表

AGENTS.md 中的技能表条目要求

部署或升级 record-bug-fix-memory 后，在 AGENTS.md 的技能表中生成的条目必须包含以下信息，确保 agent 能正确使用双层架构：

- `record-bug-fix-memory` — `.agents/skills/fix-bug/record-bug-fix-memory/SKILL.md` — bug 修复后的经验与事故记录沉淀（非调试流程本身）。
  - **存储架构**：双层存储。SKILL.md 只放流程指导和摘要索引，详细案例存储在同目录下的独立 `YYYY-MM-DD-{slug}.md` 文件中。
  - **阅读方式**：使用此技能前，先读 SKILL.md 了解流程，再根据「案例索引」章节按需读取相关的独立案例文件。
  - **写入方式**：新增经验时，创建独立案例文件，同时在 SKILL.md 的「案例索引」追加摘要。禁止将完整事故正文写入 SKILL.md。

这段描述确保任何 agent 在读取 AGENTS.md 后，都能准确理解：

1. 经验教训不在 SKILL.md 正文里，而在同目录的独立文件中
2. 需要先读索引，再按需读详细案例
3. 写入时必须创建独立文件，不能往 SKILL.md 里堆内容

交互选择详细说明

AskUserQuestion 调用规范

在步骤 3 交互选择时，必须按以下格式调用 AskUserQuestion 工具：

1. 问题标题：使用 header: "记忆项"
2. 问题内容：清晰说明当前扫描结果和可选操作
3. 多选模式：设置 multiSelect: true
4. 选项设计：
   • 每个可用记忆项作为一个选项
   • label 格式：记忆项名称 [状态]
   • description 说明该选项的具体操作

选项状态标注规则

• [缺失]：目标文件中不存在该二级标题
• [需更新]：标题存在但内容与模板有差异（缺少行/段落）
• [已完整]：内容与模板完全一致

用户选择后的处理

1. 用户选择 [缺失] 状态的记忆项 → 在合适位置插入完整模板内容
2. 用户选择 [需更新] 状态的记忆项 → 执行差异对比，仅补全缺失部分
3. 用户选择 [已完整] 状态的记忆项 → 跳过或提示无需更新

触发场景

本技能应在以下场景主动调用：

明确触发

1. 用户提及 "init-ai-md"
2. 用户提及 "初始化记忆文件"
3. 用户提及 "更新 AGENTS.md"
4. 用户提及 "同步 AI 记忆"

上下文触发

5. 用户新建项目时（建议初始化）
6. 用户克隆项目后首次使用 Claude Code
7. 用户询问如何规范化 AI 记忆文件
8. 用户抱怨 AI 记忆文件内容混乱或缺失

注意事项

核心原则

1. 交互优先：在处理前必须与用户交互确认，不得自动全量处理
2. 增量补全：仅补全缺失内容，不全量替换
3. 保护自定义：用户的自定义内容不得被覆盖
4. 禁止脚本：不得使用任何脚本进行批处理

执行要求

1. 中文优先：所有生成和更新的内容必须使用简体中文
2. 顺序插入：严格按照模板文件的数字前缀顺序插入
3. 标题来源：使用模板内的二级目录标题，而非文件名
4. 前置插入：新增记忆项插入到原有二级目录之前
5. 询问确认：技能删除时必须询问用户；CLAUDE.md/GEMINI.md 重定向属于固定迁移动作，不需要询问

格式保持

1. 保持原有文档的一级标题不变
2. 保持原有文档的项目特定内容不变
3. 仅更新/插入通用提示词部分

差异对比判断

判断内容需要更新的依据：

• 二级目录标题相同但内容不完整
• 模板中存在目标文件缺少的行或段落
• 模板中存在目标文件缺少的子标题或列表项

禁止事项清单

• 禁止未经用户选择直接处理所有记忆项
• 禁止使用 Python/TypeScript/Shell 等脚本批量处理
• 禁止一股脑复制粘贴整个模板文件内容
• 禁止覆盖用户在 AGENTS.md 中的自定义内容
• 禁止跳过交互选择步骤直接执行更新

模板内容参考

详细的模板内容请查看 templates/ 目录下的各个模板文件。

---

参考资源

• Claude Code 文档: https://code.claude.com/docs/zh-CN/skills
• 技能最佳实践: https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/best-practices