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/ 为 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 的格式
   • 为每个扫描到的技能生成一条条目，格式如下：

     - `{技能名称}`
       - 路径：`{技能相对路径}`
       - 用途：{技能描述}
       - 触发时机：{从技能 SKILL.md 中提取的使用场景}
       - 参考作用：{从技能 SKILL.md 中提取的参考信息}
       - 约束：{从技能 SKILL.md 中提取的边界约束}
     

   • 特殊处理 record-bug-fix-memory：该技能采用双层存储架构，技能表条目必须额外包含存储架构说明和阅读指引，格式如下：

     - `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. 回读并确认两个文件内容逐字一致；此固定迁移动作不需要询问用户

模板文件规范

目录结构

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

用户：请帮我初始化 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