# Init AI Md

> 初始化、迁移和增量更新项目 AI 记忆文件，以 AGENTS.md 作为唯一事实来源。 通过交互式选择和差异对比，智能补全记忆项内容。触发条件： 当用户提及初始化记忆文件、更新 AGENTS.md、迁移 CLAUDE.md/GEMINI.md、同步 AI 记忆、 init-ai-md 等关键词时主动调用。 Use when initializing, migrating, or incrementally updating project AI memory documents. The skill maintains the canonical root AGENTS.md, redirects CLAUDE.md and GEMINI.md, and manages the project-level record-bug-fix-memory skill.

- Skill: `ruan-cat/init-ai-md` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add ruan-cat/init-ai-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruan-cat/init-ai-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ruan-cat (https://skillmd.com/u/ruan-cat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ruan-cat/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` 必须删除全部原有内容，只保留：

  ```text
  请阅读本项目根目录内的 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. **询问示例**：

   ```plain
   请选择需要处理的记忆项：

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

4. **等待用户选择**：
   - 用户可多选需要处理的记忆项
   - 用户可选择"其他"输入自定义需求

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

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

1. **逐行对比原则**：
   - 深度阅读目标文件中该记忆项的完整内容
   - 深度阅读模板文件中该记忆项的完整内容
   - 逐行/逐段落进行对比

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

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

4. **示例**：

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

   ```markdown
   ## 编写测试用例规范

   测试文件使用 `*.test.ts`，放在项目的 tests 目录中。

   - 使用 `describe` 和 `test` 组织测试用例
   ```

   对应模板的内容：

   ```markdown
   ## 编写测试用例规范

   测试文件使用 `*.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/` 为 canonical，补入旧路径中缺失的独立案例；同名文件不覆盖

3. **检查项目现有技能**（新格式）：
   - 检查项目中是否已存在 `.agents/skills/fix-bug/record-bug-fix-memory/SKILL.md`
   - 如果不存在（且无旧格式可迁移）：标记为 `[可部署]`，并在情况 A 中无条件部署
   - 如果已存在：读取其 frontmatter 中的 `template-version` 字段
     - 无版本号或版本 < 2.0.0：标记为 `[需升级]`
     - 版本 ≥ 2.0.0：标记为 `[已是最新]`

4. **判断是否为旧版单层架构**：
   - 如果标记为 `[需升级]`，检查现有 SKILL.md 是否内嵌了大段事故记录正文
   - 判断方法：检测 `###` 三级标题下是否存在超过 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 中内嵌的每条事故记录（`###` 三级标题 + 正文）
   - 为每条记录创建独立的案例文件 `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` 的格式
   - 为每个扫描到的技能生成一条条目，格式如下：
     ```markdown
     - `{技能名称}`
       - 路径：`{技能相对路径}`
       - 用途：{技能描述}
       - 触发时机：{从技能 SKILL.md 中提取的使用场景}
       - 参考作用：{从技能 SKILL.md 中提取的参考信息}
       - 约束：{从技能 SKILL.md 中提取的边界约束}
     ```
   - **特殊处理 `record-bug-fix-memory`**：该技能采用双层存储架构，技能表条目必须额外包含存储架构说明和阅读指引，格式如下：
     ```markdown
     - `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。
     ```

3. **插入或更新 AGENTS.md**：
   - 如果 AGENTS.md 中已存在「## 本项目的技能表」章节：执行差异对比，仅补全新增或变更的技能条目
   - 如果不存在：将技能表章节插入到 AGENTS.md 的**一级标题之后、其他二级标题之前**（即紧跟在文件开头的项目描述之后）

4. **技能表位置要求**：
   - 技能表**必须**位于所有其他二级标题之前
   - 这确保 agent 在读取 AGENTS.md 时最先看到可用的技能清单

### 步骤 7：收敛旧 AI 记忆文件

1. 检查项目根目录是否存在 `CLAUDE.md` 或 `GEMINI.md` 文件
2. 如果存在这些文件，删除全部原有内容（包括 frontmatter、标题和项目规则）
3. 仅写入：`请阅读本项目根目录内的 AGENTS.md 文档。@AGENTS.md`
4. 回读并确认两个文件内容逐字一致；此固定迁移动作不需要询问用户

## 模板文件规范

### 目录结构

```plain
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 技能模板
```

### 模板文件命名规范

- **前缀**：两位数字（01-99），决定插入顺序
- **分隔符**：使用英文句点 `.`
- **名称**：中文描述性名称
- **后缀**：`.md`

### 模板内容规范

1. 模板文件**只包含二级目录**，不包含一级目录
2. 单个模板可包含多个二级目录
3. 二级目录标题即为插入后的章节标题
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：全新项目初始化

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

执行流程：

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

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

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

执行流程：

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

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

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

执行流程：

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

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

```markdown
用户：请帮我初始化 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：增量更新时发现新技能

```markdown
用户：请更新我的 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`）：

```markdown
- `{技能名称}`
  - 路径：`.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 能正确使用双层架构：

```markdown
- `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/](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