Init Ai Md

---
name: init-ai-md
description: 初始化和增量更新 AI 记忆文件（CLAUDE.md、AGENTS.md、GEMINI.md）。通过交互式选择和差异对比，智能补全记忆项内容。触发条件：当用户提及初始化记忆文件、更新 CLAUDE.md、同步 AI 记忆、init-ai-md 等关键词时主动调用。
user-invocable: true
metadata:
  version: "0.13.4"
---

# init-ai-md 技能说明

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

## 核心功能

1. **初始化 CLAUDE.md**：检查并创建项目的 AI 记忆文件
2. **交互式选择**：扫描现有内容和可用模板，让用户选择需要的记忆项
3. **差异对比补全**：深度对比文本差异，仅补全缺失内容而非全量替换
4. **多文件同步**：支持同步更新 AGENTS.md 和 GEMINI.md

## 执行流程

### 步骤 1：检查 CLAUDE.md 文件

1. 检查项目根目录是否存在 `CLAUDE.md` 文件
2. 如果不存在：
   - 先执行 Claude Code 内部的 `/init` 斜杠命令
   - 确保生成的 `CLAUDE.md` 文件以**中文**编写
3. 如果已存在：
   - 读取现有内容，准备进行扫描分析

### 步骤 2：扫描分析

1. **扫描目标文件**：
   - 提取 `CLAUDE.md` 中所有的**二级标题**（`## xxx`）
   - 记录每个二级标题下的内容摘要
   - 建立现存记忆项清单

2. **扫描模板目录**：
   - 读取 `templates/` 目录下的所有模板文件名
   - 按照**数字前缀顺序**排序（如 `01.xxx.md`、`02.xxx.md`）
   - 提取每个模板文件内的二级标题
   - 建立可用记忆项清单

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

### 步骤 3：交互选择

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

1. **展示扫描结果**：
   - 列出当前 CLAUDE.md 中已存在的记忆项（二级标题列表）
   - 列出 templates 目录中可用的记忆项

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

3. **询问示例**：

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

   选项：
   - 主动问询实施细节 [需更新] - 内容存在差异，将补全缺失部分
   - 编写测试用例规范 [缺失] - 将新增此记忆项
   - 报告编写规范 [已完整] - 内容一致，无需更新
   - 获取技术栈对应的上下文 [需更新] - 缺少部分链接
   ```

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

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

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

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

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

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

4. **示例**：

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

   ```markdown
   ## 获取技术栈对应的上下文

   ### claude code skill

   - 编写语法与格式： https://code.claude.com/docs/zh-CN/skills
   - 最佳实践： https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/best-practices
   ```

   模板文件 `99.获取技术栈对应的上下文.md` 的内容：

   ```markdown
   ## 获取技术栈对应的上下文

   在处理特定技术栈相关的问题时，你应该主动获取对应的上下文文档和最佳实践。

   ### claude code skill

   - 编写语法与格式： https://code.claude.com/docs/zh-CN/skills
   - 最佳实践： https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/best-practices
   - 规范文档： https://agentskills.io/home
   ```

   **正确的处理方式**：
   - 识别缺失内容：
     - 缺失描述段落："在处理特定技术栈相关的问题时，你应该主动获取对应的上下文文档和最佳实践。"
     - 缺失列表项："- 规范文档： https://agentskills.io/home"
   - 在原有内容的对应位置补全这两处缺失
   - **不要**全量替换整个章节

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

### 步骤 5：同步其他 AI 记忆文件

1. 检查项目根目录是否存在 `AGENTS.md` 或 `GEMINI.md` 文件
2. 如果存在这些文件：
   - **必须**使用 `AskUserQuestion` 工具询问用户
   - 询问是否用更新后的 `CLAUDE.md` 全量替换这些文件
3. 根据用户选择执行替换操作

## 模板文件规范

### 目录结构

```plain
init-ai-md/
├── SKILL.md              # 技能说明文件
└── templates/            # 模板文件目录
    ├── 01.主动问询实施细节.md
    ├── 02.编写测试用例规范.md
    ├── 03.报告编写规范.md
    ├── 04.生成发版日志的操作规范.md
    ├── 05.沟通协作要求.md
    └── 99.获取技术栈对应的上下文.md
```

### 模板文件命名规范

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

### 模板内容规范

1. 模板文件**只包含二级目录**，不包含一级目录
2. 单个模板可包含多个二级目录
3. 二级目录标题即为插入后的章节标题
4. 内容使用简体中文编写

## 执行示例

### 场景 1：全新项目初始化

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

执行流程：

1. 检测到无 CLAUDE.md → 执行 /init 命令
2. 扫描 templates/ 目录，建立可用记忆项清单
3. 使用 AskUserQuestion 询问用户需要哪些记忆项
4. 用户选择后，按序号顺序插入选中的模板内容
5. 检测到无 AGENTS.md/GEMINI.md → 完成
```

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

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

执行流程：

1. 检测到已有 CLAUDE.md → 读取现有内容
2. 扫描现有二级标题，建立现存记忆项清单
3. 扫描 templates/ 目录，建立可用记忆项清单
4. 对比分析，标注每个记忆项的状态（缺失/需更新/已完整）
5. 使用 AskUserQuestion 询问用户需要处理哪些记忆项
6. 用户选择后，对每个选中项执行差异对比和增量补全
7. 检测到存在 AGENTS.md → 询问用户是否同步替换
8. 用户确认后执行替换
```

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

```markdown
用户：更新 CLAUDE.md 中的"获取技术栈对应的上下文"章节

执行流程：

1. 读取 CLAUDE.md 中该章节的完整内容
2. 读取模板 99.获取技术栈对应的上下文.md 的内容
3. 逐行对比，发现：
   - 缺失描述段落
   - 缺失"规范文档"链接
4. 在对应位置补全缺失内容
5. 保持原有的自定义内容不变
```

## 交互选择详细说明

### AskUserQuestion 调用规范

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

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

### 选项状态标注规则

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

### 用户选择后的处理

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

## 触发场景

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

### 明确触发

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

### 上下文触发

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

## 注意事项

### 核心原则

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

### 执行要求

1. **中文优先**：所有生成和更新的内容必须使用简体中文
2. **顺序插入**：严格按照模板文件的数字前缀顺序插入
3. **标题来源**：使用模板内的二级目录标题，而非文件名
4. **前置插入**：新增记忆项插入到原有二级目录**之前**
5. **询问确认**：同步 AGENTS.md/GEMINI.md 前必须询问用户

### 格式保持

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

### 差异对比判断

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

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

### 禁止事项清单

- **禁止**未经用户选择直接处理所有记忆项
- **禁止**使用 Python/TypeScript/Shell 等脚本批量处理
- **禁止**一股脑复制粘贴整个模板文件内容
- **禁止**覆盖用户在 CLAUDE.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