init-ai-md

init-ai-md skill description

This skill is used to quickly initialize and incrementally update the AI memory file in a project. Throughinteractive selectionanddiff comparison completion, it helps users precisely manage the content of the AI memory file.

Core Features

Initialize AGENTS.md: Check for and create the project's sole AI memory file
Interactive selection: Scan existing content and available templates, letting the user choose the memory items they need
Diff comparison completion: Deeply compare text differences, completing only missing content rather than replacing everything
Legacy mode migration: Restore the content of legacy CLAUDE.md / GEMINI.md to AGENTS.md, and clear both old files into redirects; migrate the record-bug-fix-memory
Skill table management: Scan the project's .agents/skills/ directory for existing skills, and create and maintain the "Skill Table of This Project" section in AGENTS.md
Built-in skill initialization: Support deploying built-in skill templates such as record-bug-fix-memory to the project's .agents/skills/ directory

Single Document and Legacy Mode Handling

AGENTS.md is the single source of truth; all template sections and skill tables are written only to this file.
The CLAUDE.md、GEMINI.md existing in the root directory must have all original content deleted, keeping only:

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

On every execution, delete the "Get context corresponding to the tech stack" second-level section and its body from AGENTS.md .
record-bug-fix-memory is installed unconditionally when missing; when the old .claude/skills path exists, migrate it to .agents/skills。

Document Reading Strategy

On the first pass, read only the directory/title structure (grep "^##" file)
As needed for the task, use offset/limit to read only the relevant sections
When updating the document, use Edit's precise replacement; do not Read the full text and then Write the full text

Execution Flow

Step 1: Check the AGENTS.md file

Check whether the project root directory contains the AGENTS.md、CLAUDE.md、GEMINI.md file
If AGENTS.md does not exist:
- If a non-empty CLAUDE.md or GEMINI.mdexists, first migrate its content into the new AGENTS.md
- If both legacy files exist and their content differs, use AskUserQuestion to let the user choose the content to keep
- If none of the three exist or all are empty, create AGENTS.md, and ensure the content is written inChineseWrite
If AGENTS.md already exists:
- Read the existing content and prepare for scan analysis
For the CLAUDE.md、GEMINI.md existing in the root directory, delete all original content, keeping only:
- 请阅读本项目根目录内的 AGENTS.md 文档。@AGENTS.md
From AGENTS.md , delete the "Get context corresponding to the tech stack" second-level section and its body

Step 2: Scan Analysis

Scan the target file：
- Extract all of the AGENTS.md inLevel-2 headings（## xxx）
- Record a content summary under each level-2 heading
- Build a list of existing memory items
Scan the template directory：
- Read templates/ all template file names in the directory (excluding deleted tech stack context templates)
- According tonumeric prefix ordersort (e.g., 01.xxx.md、02.xxx.md）
- Extract the level-2 headings in each template file
- Build a list of available memory items
Comparative analysis：
- Compare existing memory items with available memory items
- Identify three types of situations:
  - Missing: memory items that are in the template but not in the target file
  - Needs update: memory items with the same heading but differing content
  - Complete: memory items whose content is completely identical

Step 3: Interactive selection

MustUse AskUserQuestion tools to interact with the user:

Show scan results：
- List the memory items already present in the current AGENTS.md (list of level-2 headings)
- List the available memory items in the templates directory
Generate selection questions：
- Use AskUserQuestion tool's multiSelect: true mode
- Make each available memory item an option
- Indicate the current status of the memory item in the option description:
  - [缺失] - does not exist in the target file
  - [需更新] - exists but content is incomplete
  - [已完整] - content is already completely identical
- The default recommended selected status is[缺失]and[需更新]memory items

Ask for examples：

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

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

Wait for user selection：
- The user may select multiple memory items to process
- The user may select "Other" to enter custom requirements

Step 4: Difference comparison and incremental completion

For each memory item selected by the user, performfine-grained difference comparison：

Line-by-line comparison principle：
- Deeply read the complete content of that memory item in the target file
- Deeply read the complete content of that memory item in the template file
- Compare line by line/paragraph by paragraph
Identify difference types：
- Missing line: a line that is in the template but not in the target file
- Missing paragraph: a complete paragraph that is in the template but not in the target file
- Missing subheading: a level-3/level-4 heading and its content that are in the template but not in the target file
- Content difference: same position but different text (handle with caution; it may be user-customized content)
Incremental completion strategy：
- Only complete missing content, do not replace everything
- Preserve existing custom content in the target file
- Insert missing lines/paragraphs at appropriate positions
- Preserve the logical order and hierarchical structure of the content
Example：

Assume the target file AGENTS.md contains the following content:
```
## 编写测试用例规范

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

- 使用 `describe` 和 `test` 组织测试用例
```
Content of the corresponding template:
```
## 编写测试用例规范

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

- 使用 `describe` 和 `test` 组织测试用例
```
Correct handling method：
- Identify missing content:
  - Missing list item: "- Use describe and test to organize test cases"
- Complete the missing items at the corresponding positions in the original content
- Do notreplace the entire section wholesale
Prohibitions：
- ProhibitedUse any form of scripting for batch processing (Python, TypeScript, Shell, etc.)
- Prohibitedcopy and paste the entire template content all at once
- Prohibitedoverwrite the user's customized content

Step 5: Initialize or upgrade local skills

After completing the AGENTS.md content update, check whether the project needs to deploy or upgrade built-in skills:

Check the skill template directory：
- Read the templates/record-bug-fix-memory/ directory, and confirm that the built-in skill template is available
- Read the template's template-version field (currently 2.0.0）
Detect legacy format remnants(migration detection):
- Check whether the legacy format exists in the project .claude/skills/fix-bug/record-bug-fix-memory/SKILL.md
- If the legacy format exists, and the new path .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md does not exist: mark as [旧格式可迁移]
- The migration operation only handles record-bug-fix-memory, moves its content to .agents/skills/fix-bug/record-bug-fix-memory/, and then deletes the old skill directory
- If the new path already exists, use .agents/skills/ as canonical, add the missing independent cases from the old path; do not overwrite files with the same name
Check the project's existing skills(new format):
- Check whether the project already contains .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md
- If it does not exist (and there is no legacy format to migrate): mark as [可部署], and deploy unconditionally in Case A
- If it already exists: read the template-version field in its frontmatter
  - No version number or version < 2.0.0: mark as [需升级]
  - Version ≥ 2.0.0: mark as [已是最新]
Determine whether it is the old single-layer architecture：
- If marked as [需升级], check whether the existing SKILL.md embeds a large section of incident record body text
- Determination method: detect whether ### has a content block of more than 10 lines under the level-three heading
- If embedded cases exist: mark as [需升级 + 需拆分]
Execute deployment or upgrade: no longer ask whether to install or migrate; the status is only used to select the following handling branches.

Case A: Fresh deployment ([可部署]）
- Copy templates/record-bug-fix-memory/SKILL.md to the project's .agents/skills/fix-bug/record-bug-fix-memory/SKILL.md
- Create the necessary directory structure
- The "Case Index" section in the template is initially empty and will be gradually supplemented as the project accumulates
Case B: Upgrade skeleton ([需升级], no embedded cases)
- Replace the corresponding section of the existing SKILL.md with the process guidance part of the template
- Preserve the existing case index content in the project (if any)
- Preserve the existing independent case files in the same directory
Case C: Upgrade + split ([需升级 + 需拆分]）
- Extract each incident record embedded in SKILL.md (### level-3 heading + body)
- Create a separate case file for each record YYYY-MM-DD-{slug}.md
  - extract the date from the heading (if any), otherwise use the current date
  - generate the slug from heading keywords
- In the "Case Index" section of SKILL.md, generate a summary index for each split-out case
- Replace the SKILL.md skeleton with the process guidance section from the template
- The final SKILL.md retains only the process guidance + summary index, and no longer contains the incident body text
Case D: Legacy format migration ([旧格式可迁移]）
- Detected .claude/skills/fix-bug/record-bug-fix-memory/ legacy-format skills under
- The project uniformly uses .agents/skills/ as the skills directory
- Create the .agents/skills/fix-bug/ directory (if it does not exist)
- Completely move the legacy skill files and standalone cases to .agents/skills/fix-bug/record-bug-fix-memory/
- Delete the migrated legacy record-bug-fix-memory directories, and do not process other .claude/skills/ skills
- After migration is complete, re-run the skill scan and skill table generation from step 6 according to the new format
- Note: migration only moves files and does not modify case body text; path references inside SKILL.md are maintained by each skill itself
Case E: Already up to date ([已是最新]）
- Do not replace the project's existing skill body text, case index, or standalone case files
- Only check the target path and version field, then continue to step 6

Step 6: Generate/update the "Skill Table for This Project"

After step 5 is complete (regardless of whether new skills were deployed), the skill table must be generated or updated:

Scan project skills：
- Scan all .agents/skills/ files under the project's SKILL.md directory
- If .agents/skills/ does not exist, fall back to checking .claude/skills/(legacy format leftover); if the legacy format exists, prompt the user to perform the migration operation from step 5 first
- Read each skill's name and description(extracted from the YAML frontmatter)
- Record the relative path of each skill

Generate skill table content：

Refer to the format of templates/08.本项目的技能表.md format

Generate an entry for each scanned skill in the following format:

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

Special handling for record-bug-fix-memory: this skill uses a two-layer storage architecture; its skill table entry must additionally include a storage architecture description and reading guidance in the following format:

- `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。

Insert or update AGENTS.md：
- If the "## Skill Table for This Project" section already exists in AGENTS.md: perform a diff comparison, and only fill in newly added or changed skill entries
- If it does not exist: insert the skill table section into AGENTS.md'safter the level-1 heading and before other level-2 headings(that is, immediately after the project description at the beginning of the file)
Skill table location requirements：
- The skill tablemustbe located before all other level-2 headings
- This ensures that when the agent reads AGENTS.md, it sees the available skill list first

Step 7: Consolidate old AI memory files

Check whether the project root directory contains CLAUDE.md or GEMINI.md files
If these files exist, delete all original content (including frontmatter, headings, and project rules)
Write only:请阅读本项目根目录内的 AGENTS.md 文档。@AGENTS.md
Read back and confirm that the contents of the two files are identical word for word; this fixed migration action does not require asking the user

Template file specification

Directory structure

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

Template file naming convention

Prefix: two digits (01-99), determines insertion order
Separator: use the English period .
Name: Chinese descriptive name
Suffix：.md

Template content specification

Template filecontains only second-level headings, not first-level headings
A single template may contain multiple second-level headings
The second-level heading title is the section title after insertion
Content is written in Simplified Chinese

Built-in skill template specification

templates/ In addition to memory item templates with numeric prefixes, the directory may also contain subdirectories in the form ofbuilt-in skill templates：

Built-in skill templates are stored in independent subdirectories (e.g., templates/record-bug-fix-memory/）
Each built-in skill template directory must contain the SKILL.md file
The built-in skill template's SKILL.md follows the YAML frontmatter specification of Claude Code Skills
Built-in skill templates should not contain project-specific content (such as specific repository-level incident records); such content should be accumulated by the project after deployment
When a built-in skill template is deployed to a project, the target path is .agents/skills/{类别}/{技能名}/SKILL.md

Execution examples

Scenario 1: Initializing a brand-new project

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

执行流程：

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

Scenario 2: Incrementally updating an existing project

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

执行流程：

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

Scenario 3: Example of completing a diff comparison

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

执行流程：

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

Scenario 4: Initializing local skills and generating a skill table

用户：请帮我初始化 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 写入固定重定向并完成验收

Scenario 5: Discovering new skills during incremental updates

用户：请更新我的 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 → 删除旧内容并写入固定重定向

Detailed description of skill table management

Purpose of the skill table

The purpose of the "This project's skill table" section is to enable the agent, when reading AGENTS.md, toquickly understand the list of skills available in the project, including:

Skill names and paths
The purpose and trigger timing of skills
The reference role and constraints of skills

This helps the agent proactively invoke the correct skill in appropriate scenarios without needing to scan .agents/skills/ directory one by one.

Skill table entry format

Each skill entry follows the format below (refer to templates/08.本项目的技能表.md）：

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

Skill table update strategy

When adding a skill: scan and discover a new SKILL.md → append an entry at the end of the skill table
When a skill changes: detect a change in skill description or path → update the corresponding entry
When a skill is deleted: scanning does not find a recorded skill → use AskUserQuestion to ask the user whether to remove the entry

Detailed description of built-in skill deployment

record-bug-fix-memory skill

This is a skill dedicated to accumulating bug fix experience, using adual-layer storage architectureAfter deployment:

Target path：.agents/skills/fix-bug/record-bug-fix-memory/SKILL.md
Source template：templates/record-bug-fix-memory/SKILL.md（template-version: 2.0.0）
Two-tier storage architecture：
- SKILL.md: contains only process guidance + case summary index (kept concise)
- Independent case files: each detailed incident record is written as YYYY-MM-DD-{slug}.md, in the same directory as SKILL.md
- ProhibitedEmbedding the full text of incident records into SKILL.md
Post-deployment state：
- The skill's general framework is ready (overview, when to use, recording process, case file specification, etc.)
- The "Case Index" section is empty, waiting for actual project accumulation
- The agent can immediately use this skill to record bug fix experience
Continuous evolution：
- After each bug fix, the agent creates an independent case file YYYY-MM-DD-{slug}.md
- At the same time, append a summary index entry to the "Case Index" section of SKILL.md
- This allows the skill to gradually become richer with project use, while keeping SKILL.md concise and readable

Deployment notes

Fresh deployment: if the target path does not exist, create the directory structure and deploy the template
Upgrade deployment: if an older version already exists (no template-version or < 2.0.0), execute the upgrade process (see step 5)
Will not overwrite cases: during upgrade, preserve the project's existing independent case files
Skill table sync: after deployment is complete, automatically update the skill table in AGENTS.md

Requirements for the skill table entry in AGENTS.md

After deploying or upgrading record-bug-fix-memory , the entry generated in the skill table of AGENTS.mdmustcontain the following information to ensure the agent can correctly use the two-tier architecture:

- `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。

This description ensures that any agent, after reading AGENTS.md, can accurately understand:

Lessons learned are not in the body of SKILL.md, but in independent files in the same directory
The index must be read first, then detailed cases read on demand
When writing, independent files must be created; content must not be piled into SKILL.md

Detailed explanation of interactive selection

AskUserQuestion invocation specification

During the interactive selection in step 3, the following format must be used to invoke the AskUserQuestion tool:

Question title: use header: "记忆项"
Question content: clearly explain the current scan results and available operations
Multi-select mode: set multiSelect: true
Option design：
- Each available memory item as one option
- label format:记忆项名称 [状态]
- description describe the specific operation of that option

Option status annotation rules

[缺失]: the secondary heading does not exist in the target file
[需更新]: the heading exists but the content differs from the template (missing lines/paragraphs)
[已完整]: the content is completely identical to the template

Handling after user selection

The user selects a memory item in [缺失] state → insert the complete template content at an appropriate position
The user selects a memory item in [需更新] state → perform a diff comparison and fill in only the missing parts
The user selects a memory item in [已完整] state → skip or indicate that no update is needed

Trigger Scenarios

This skill should be used in the following scenariosActive Invocation：

Explicit Trigger

User mentions "init-ai-md"
User mentions "initialize memory file"
User mentions "update AGENTS.md"
User mentions "sync AI memory"

Contextual Trigger

When the user creates a new project (initialization recommended)
When the user uses Claude Code for the first time after cloning a project
When the user asks how to standardize AI memory files
When the user complains that the AI memory file content is messy or missing

Notes

Core Principles

Interaction First: Before processing, must interact with the user for confirmation; automatic full processing is not allowed
Incremental Completion: Only complete missing content, do not replace in full
Protect Customizations: User custom content must not be overwritten
No Scripts: Must not use any scripts for batch processing

Execution Requirements

Chinese First: All generated and updated content must use Simplified Chinese
Sequential Insertion: Strictly insert in the order of the numeric prefixes in the template file
Heading Source: Use the second-level heading titles within the template, not the file names
Insert Before: Insert new memory items before the existing second-level headingbefore
Ask for Confirmation: When deleting skills, must ask the user;CLAUDE.md/GEMINI.md redirection is a fixed migration action and does not require asking

Preserve Format

Keep the first-level heading of the original document unchanged
Keep the project-specific content of the original document unchanged
Only update/insert the general prompt sections

Difference Comparison Judgment

Basis for determining that content needs updating:

The second-level heading title is the same but the content is incomplete
The template contains lines or paragraphs that are missing from the target file
The template contains subheadings or list items that are missing from the target file

Prohibited Items List

ProhibitedProcessing all memory items directly without user selection
ProhibitedUsing scripts such as Python/TypeScript/Shell for batch processing
ProhibitedCopying and pasting the entire template file content wholesale
ProhibitedOverwriting the user's custom content in AGENTS.md
ProhibitedSkipping the interactive selection step and executing updates directly

Template Content Reference

For detailed template content, please see templates/ the individual template files under the directory.

Reference Resources

Claude Code Documentation: https://code.claude.com/docs/zh-CN/skills
Skill Best Practices: https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/best-practices