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. 询问示例：

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

4. 等待用户选择：

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

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

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

1. 逐行对比原则：

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

2. 识别差异类型：

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

3. 增量补全策略：

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

4. 示例：

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

   ## 获取技术栈对应的上下文
   
   ### 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 的内容：

   ## 获取技术栈对应的上下文
   
   在处理特定技术栈相关的问题时，你应该主动获取对应的上下文文档和最佳实践。
   
   ### 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. 根据用户选择执行替换操作

模板文件规范

目录结构

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：全新项目初始化

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

执行流程：

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

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

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

执行流程：

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

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

用户：更新 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/ 目录下的各个模板文件。

---

参考资源

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