init

name	init
description	当用户要求初始化仓库或目录、生成或更新 AGENTS.md、归档 agent 配置、收集 skill 或整理目录， 或说“init”“初始化”时使用。
metadata	{"openclaw":{"emoji":"📦"}}

init — 逐目录初始化 AGENTS.md 并归档各 agent 的初始化文件

执行前置

遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。

为本库的每一个目录执行初始化。

核心原则

1. 两阶段执行：先只读调查（阶段 A），确认后再统一执行写操作（阶段 B）， 避免边扫边改导致信息丢失（如先重命名了 .claude，后续就无法再参考其内容）。
2. 先参考后归档：归档对象仅作格式参考，任何 agent 文件/目录先完整读取与复制，再重命名。
3. 只复制，不移动：skill 归集均为复制，原位置保留。
4. 幂等：已归档（*.bak）与已归集内容不再处理；第二次运行应输出"无变更"。
5. 不确定就问，一次问全：无法判定外来文件夹/agent 生成内容时询问用户，不臆断； 所有问题在第一次交互一次性全部提出（编号列表），用户一次回答，不逐次追问。
6. 循环尝试直至成功：阶段 B 中断或重命名冲突时重新运行即可收敛（幂等保证不重复处理）； 多次失败向用户报告进展，不无限循环。
7. 全局配置禁区：仅处理本库范围内内容；全局目录（~/.claude、~/.codex 等）只参考、不重命名。

触发时机

• 用户要求初始化仓库/目录："init"、"初始化"、"生成AGENTS.md"、"为每个目录生成AGENTS.md"
• 用户要求归档 agent 初始化文件："归档agent配置"、"重命名CLAUDE.md"、"处理.claude/.codex"
• 用户要求整理/收集 skills："收集skill"、"把生成内容的skill放到git家目录的.opencode/skills"、 "归档skill"、"合并skill到.opencode/skills"、"收集散落的skill"
• 用户要求预演/确认："dry-run"、"预演"、"先看看会改什么"（只读调查，不写文件）
• 与其他技能配合：归档前后查看改动 → diff；初始化完成打标 → tag；初始化报错 → debug； 仓库结构梳理 → analy；优化 skill 库 → up；生成类任务全流程 → make

各 agent 的初始化文件与配置目录（识别清单）

Agent	init 文件	配置/技能目录
Claude Code	CLAUDE.md	.claude/（skills、commands、agents）
OpenAI Codex	CODEX.md（也读 AGENTS.md）	.codex/（skills、prompts）
Cursor	.cursorrules、.cursor/rules/*.mdc	.cursor/（skills、rules）
GitHub Copilot	.github/copilot-instructions.md	.copilot/、.github/prompts/
百度 Comate	无独立 init 文件（读 AGENTS.md）	.comate/
腾讯 CodeBuddy	无独立 init 文件（读 AGENTS.md）	.codebuddy/
Windsurf	.windsurf/rules/*.md	.windsurf/（skills）
Gemini CLI	GEMINI.md	.gemini/
opencode	AGENTS.md（标准，不重命名）	.opencode/（agents、commands、skills）
其他	上述未列出的 *.md/隐藏目录	同类处理

若某目录出现清单外的新 agent 文件/目录，按同一规则处理并在汇总中登记， 便于后续维护清单。

命名与时间戳约定

对象类型	示例	重命名后
init 文件	CLAUDE.md	.CLAUDE.md.<时间戳>.bak
init 文件	CODEX.md	.CODEX.md.<时间戳>.bak
init 文件	GEMINI.md	.GEMINI.md.<时间戳>.bak
init 文件	.cursorrules	.cursorrules.<时间戳>.bak
init 文件	.github/copilot-instructions.md	.github/copilot-instructions.md.<时间戳>.bak
技能目录	.claude	.claude.md.<时间戳>.bak
技能目录	.codex	.codex.md.<时间戳>.bak
技能目录	.cursor	.cursor.md.<时间戳>.bak
技能目录	.copilot	.copilot.md.<时间戳>.bak
技能目录	.comate	.comate.md.<时间戳>.bak
技能目录	.codebuddy	.codebuddy.md.<时间戳>.bak
技能目录	.windsurf	.windsurf.md.<时间戳>.bak

统一规则：<原文件/目录名>.<时间戳>.bak（技能目录在原名后加 .md）。

时间戳格式：%Y-%m-%d-%H-%M-%S（例如 2026-07-29-11-37-27），生成方式：

TS=$(date +%Y-%m-%d-%H-%M-%S)   # 例如 2026-07-29-11-37-27
mv CLAUDE.md ".CLAUDE.md.${TS}.bak"
mv CODEX.md  ".CODEX.md.${TS}.bak"
mv .claude   ".claude.md.${TS}.bak"
mv .codex    ".codex.md.${TS}.bak"
mv .comate   ".comate.md.${TS}.bak"
mv .codebuddy ".codebuddy.md.${TS}.bak"

⚠️ 禁止重命名全局配置：~/.claude、~/.codex、~/.cursor、~/.copilot、~/.comate、 ~/.codebuddy、~/.config/opencode 等为工具全局配置/技能目录，仅处理本库范围以内的 agent 文件与目录；本库根即 $HOME 时，对全局目录（如 ~/.codex 全局技能库）只参考、不重命名， 并在汇总中注明。

---

工作流程（两阶段执行：先只读调查，后统一执行）

核心原则：

• 两阶段：先只读扫描并产出变更计划（阶段 A），确认后再执行写操作（阶段 B）， 避免边扫边改导致信息丢失（如先重命名了 .claude，后续就无法再参考其内容）。
• 重命名最后统一执行：所有 mv ... .bak 放在阶段 B 的最后一步批量完成， 确保归档前所有来源（init 文件、skill 目录）都已被完整读取与复制。
• 幂等：已归档对象（*.bak）不再处理；第二次运行应输出"无变更"。
• 只复制，不移动：所有 skill 归集均为复制，原位置保留。

Step 0. 运行模式

• 默认 dry-run（只读调查）：执行阶段 A，输出完整变更计划表，询问用户确认后 再执行阶段 B；或用户明确要求（"直接执行"、"apply"）时跳过确认。
• 阶段 A 与阶段 B 的边界：阶段 A 不改动任何文件系统内容。

Step 1. 确定本库范围

• 本库根目录 = 最近的包含 .git 的祖先目录；若无 .git，则以用户指定的目录（或当前工作目录）为准。
• 收集根目录下所有子目录，自顶向下遍历：

find <repo_root> -type d \
  -not -path "*/.git*" \
  -not -path "*/node_modules*" \
  -not -path "*/__pycache__*" \
  -not -path "*/.venv*" \
  -not -path "*/build/*" \
  -not -path "*/dist/*" \
  -not -path "*/tmp/*"

排除项：.git、node_modules、__pycache__、.venv、build/、dist/、tmp/、 site-packages 等构建产物/依赖目录。被排除目录不生成 AGENTS.md，但其中的 CLAUDE.md / .claude 仍按规则归档（重命名）。

外来文件夹判定（不生成 AGENTS.md，仅处理其下已有 AGENTS.md 的归档+合并），满足其一即可：

• git 子模块（.gitmodules 中登记、git submodule status 列出）或内含独立 .git 目录；
• 知名第三方/上游项目的完整拷贝（如 lib/_oh-my-zsh、agent/LQCD_Master）；
• 与当前仓库用途无关的完整外来源码，目录名明显非本库命名惯例；
• 无法确定时：询问用户（与其余不确定点一次性全部列出，用户一次回答，不逐次追问）。

Step 2. 阶段 A — 只读调查（不写任何文件）

对每个目录（含根目录），只读收集：

1. 收集 agent init 文件：AGENTS.md、CLAUDE.md、CODEX.md、GEMINI.md、 .cursorrules、.cursor/rules/、.github/copilot-instructions.md、 .windsurf/rules/ 等（见识别清单）。完整读取内容，作为后续格式参考。
2. 外来文件夹判定：按 Step 1 标准确认；是则登记（其下已有 AGENTS.md 也登记待归档）。
3. 检测 agent 生成的新建内容（非 SKILL.md 的普通内容），判定依据（满足其一即可）：
   • 文件内容含 agent 标记，如 "generated by Claude Code / opencode"、"Created by Claude"、 "Generated by Codex"、"Comate" / "CodeBuddy" 生成标记、[Claude Code]（git tag 消息后缀）、 "AGENTS.md" 引用等；
   • git 证据：未跟踪文件（git status --porcelain 中 ?? 开头）、agent 工具身份提交 （git log --format='%an|%ae' 匹配 Claude/opencode/Codex/Comate/CodeBuddy 等）、 近期新增的非源码文件（git log --diff-filter=A）；
   • 内容符合已知 skill 的输出模式（例如 stab<N>/dev<N>/bug<N> 注释标签 → tag 技能； IMA 笔记/知识库产物 → ima-skill）；
   • SKILL.md 本身不在此步判定（其本身就是 skill，归 Step 2.5 处理），避免自我递归；
   • 无法确定时：询问用户（与其余不确定点一次性全部列出，用户一次回答，不逐次追问）。
4. 识别生成此内容的 skill（针对 Step 2.3 确认的内容）：
   • 在现有 skill 库中查找：<repo>/.claude/skills/、<repo>/.codex/skills/、 <repo>/configure/skills/、<repo>/.opencode/skills/、~/.claude/skills/、 ~/.codex/skills/、~/.config/opencode/skills/；
   • 按内容模式匹配已知 skill；若匹配到，取该 skill 的完整目录（SKILL.md + 全部附属文件， 如脚本、子文档 —— 参考 ima-skill 的多文件结构，而非仅 SKILL.md）；
   • 若无法识别但确为 agent 生成：询问用户（与其余不确定点一次性全部列出）；或根据内容反向撰写一份完整 skill （说明该内容是如何生成的）。
5. 扫描散落 skill（全库只读）：

find <repo_root> -name "SKILL.md" \
  -not -path "*/.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/build/*" \
  -not -path "*/dist/*" \
  -not -path "*/tmp/*" \
  -not -path "*/.claude.md.*.bak/*" \
  -not -path "*/.codex.md.*.bak/*" \
  -not -path "*/.AGENTS.md.*.bak" \
  -not -path "<repo_root>/.opencode/skills/*"

• 每个 SKILL.md：读取 frontmatter 的 name（无 frontmatter 时用所在目录名）， 登记待归集；已归档 .bak 目录内的 SKILL.md 跳过（防重复处理）。

6. 汇总变更计划：输出完整计划表（新建/更新 AGENTS.md 清单、待归档 init 文件清单、 skill 归集清单、待重命名目录清单、外来文件夹清单），交用户确认（dry-run 结束）。

Step 3. 阶段 B — 执行（按以下顺序写操作）

1. 创建/更新 AGENTS.md（不重命名，统一标准；外来文件夹跳过）：
   • 已存在：就地更新 —— 保留已验证有效的内容，删除过时/臆断内容，与当前代码核对；
   • 不存在：按阶段 A 收集的参考格式新建。可参考仓库根 /root/AGENTS.md 作为范本。
   • 内容规则（只保留高信号、agent 易出错的信息）：
     • 确切的命令与执行顺序（lint → typecheck → test 等）；
     • 目录结构、入口点、包边界；框架/工具链怪癖（生成代码、环境变量、构建产物）；
     • 与默认约定不同的仓库惯例；测试怪癖、必需的前置条件；
     • 排除：通用建议、冗长教程、显而易见的语言常识、无法验证的推测。
   • 保持简洁；不确定时宁可省略。
2. 在本库根目录（git 家目录）的 .opencode/skills/ 归集 skill（全部为复制）：

   # 目录 D 中的内容为 agent 生成 → 生成它的完整 skill 集中复制到本库根（git 家目录）的 .opencode/skills/
   # 散落 skill（configure/skills/、.claude/skills/ 等任意位置）同样归集于此
   mkdir -p "<repo_root>/.opencode/skills/<skill-name>"
   cp -r <skill-source-dir>/ <repo_root>/.opencode/skills/<skill-name>/   # 整个目录，非仅 SKILL.md
   

   • 所有 skill 统一集中存放于本库根（git 家目录）的 .opencode/skills/；
   • 同名同内容不重复添加（内容比对用 sha256sum，目录则比对关键文件或 diff -r）； 同名不同内容时并列保留并注明（如 <name>.v2）；
   • 原位置保留不删除，仅在汇总中登记来源。
3. 外来文件夹下 AGENTS.md 的归档+合并：
   • 按 Step 1 判定为外来文件夹的目录，若其下已有 AGENTS.md：
   • 归档：mv AGENTS.md ".AGENTS.md.${TS}.bak"（原地保留供参考）；
   • 合并：读取其内容，有价值部分并入本库根 AGENTS.md（外来组件在本库中的使用方式、 加载关系等），与本库根已有内容重复的跳过；纯外来组件自身细节不合并。
4. 统一重命名归档（最后一步，批量执行）：
   • 对阶段 A 登记的全部 agent init 文件与配置/技能目录统一执行：

   TS=$(date +%Y-%m-%d-%H-%M-%S)   # 全程使用同一时间戳
   mv CLAUDE.md  ".CLAUDE.md.${TS}.bak"
   mv CODEX.md   ".CODEX.md.${TS}.bak"
   mv .claude    ".claude.md..bak"
    .codex     
    .comate    
    .codebuddy 
   

Step 4. 验证与汇总

• 每个应初始化的目录均已有 AGENTS.md（外来文件夹除外）；
• 各 agent 的 init 文件 / 配置目录均已按 .X.md.<时间戳>.bak 规则归档，内容完好；
• 所有 agent 生成内容对应的完整 skill 均已集中复制到本库根（git 家目录）的 .opencode/skills/ 下，内容一致；
• 散落 skill 均已归集到本库根 .opencode/skills/（同名同内容跳过、差异并列保留），原位置保留；
• 外来文件夹下的 AGENTS.md 均已归档（.AGENTS.md.<时间戳>.bak）且价值内容已并入本库根 AGENTS.md；
• 幂等校验：再次以 dry-run 运行阶段 A，应输出"无变更"；
• 输出结构化汇总（见下）；若有重命名涉及 git 跟踪文件，按公共契约执行检查，不自动暂存、提交或推送。

---

错误处理

场景	处理
目录无 .git 且无用户指定目录	以当前工作目录为根，并在汇总中注明
AGENTS.md 已存在	就地更新，不重建；保留已验证内容
多个 agent init 文件并存（CLAUDE.md + CODEX.md + .cursorrules）	全部参考格式，全部按规则归档（同一时间戳）
无法判定内容是否 agent 生成	询问用户（一次问全，不逐次追问），不臆断
无法定位生成内容的 skill	询问用户（一次问全）；或据内容撰写完整 skill
本库根 .opencode/skills/ 中已有同名 skill	内容一致（sha256sum/diff -r）则跳过；不一致则并列保留并注明
散落 skill 与目标同名不同内容	并列保留（如 <name>.v2）并在汇总中注明
外来文件夹判定不确定	询问用户（一次问全），不臆断
外来文件夹下无 AGENTS.md	不创建，仅登记为外来文件夹
全局配置目录（/.claude、/.codex、/.cursor、/.copilot、/.comate、/.codebuddy 等）被误指	拒绝重命名，说明只处理本库范围内；本库根即 $HOME 时只参考不重命名
清单外的新 agent 文件/目录	按同一规则处理，并在汇总中登记
重命名目标已存在	以当前秒级时间戳重试
执行中途中断	重新运行即可：阶段 A 只读无副作用，阶段 B 幂等（已归档/已归集的自动跳过）；中断与失败原因在终端摘要中说明
阶段 B 多次失败	基于终端摘要与命令输出定位失败步骤（重命名冲突、权限、磁盘等），修正后重新执行（循环尝试直至成功）；无法解决时向用户报告
用户未确认计划即要求执行	dry-run 默认不写任何文件；执行前必须展示计划表并获确认（除非用户明确 "apply"）

Agent 输出约定

每次运行后输出结构化汇总：

✓ init 完成 (repo: /root/xxx, 模式: dry-run → apply)
  已初始化目录:  12 (AGENTS.md 新建 9 / 更新 3)
  已归档 init:   CLAUDE.md → .CLAUDE.md.2026-07-29-11-37-27.bak (3)
                 CODEX.md  → .CODEX.md.2026-07-29-11-37-27.bak (1)
                 .cursorrules → .cursorrules.2026-07-29-11-37-27.bak (1)
  skills 补充:   tag → /root/xxx/.opencode/skills/tag/ (3 个来源目录, 含附属文件)
  skill 归集:    configure/skills/{init,tag} → /root/xxx/.opencode/skills/{init,tag} (2)
  外来 AGENTS.md: lib/_oh-my-zsh/AGENTS.md → .AGENTS.md.2026-07-29-11-37-27.bak, 内容并入根 AGENTS.md (1)
  已归档配置目录: .claude → .claude.md.2026-07-29-11-37-27.bak (1)
                 .codex  → .codex.md.2026-07-29-11-37-27.bak (1, 仅参考未重命名: ~/.codex 全局)
                 .comate → .comate.md.2026-07-29-11-37-27.bak (1)
                 .codebuddy → .codebuddy.md.2026-07-29-11-37-27.bak (1)
  跳过目录:      node_modules, build, dist, tmp (4 类)
  清单外新登记:  .gemini/ (Gemini CLI, 2 处)
  幂等校验:      再次 dry-run 无变更 ✓

  提示:          git 跟踪的重命名已按公共契约检查（不自动提交或推送）

dry-run 阶段输出计划表（仅列有动作项）：

计划 (dry-run, 未写文件):
  AGENTS.md 新建: lattice-pdf, snsc, PyQCU  (3)
  AGENTS.md 更新: configure (1)
  归档:          CLAUDE.md ×3, CODEX.md ×1, .claude ×1, .comate ×1
  skill 归集:    configure/skills/init,tag → .opencode/skills/ (2)
  外来文件夹:    lib/_oh-my-zsh (AGENTS.md 归档+合并), agent/LQCD_Master (无 AGENTS.md)
  确认后执行 (输入 "apply" 或 "直接执行")

逐目录明细（仅列出有动作的目录）：

/root/xxx/lattice-pdf      AGENTS.md 新建; CLAUDE.md → .CLAUDE.md.2026-07-29-11-37-27.bak
/root/xxx/.opencode/skills tag 技能已存在; 目录含 agent 生成内容 → 本库根 .opencode/skills/tag 已确认
/root/xxx/lib/_oh-my-zsh      外来文件夹: 跳过 AGENTS.md 生成; 既有 AGENTS.md → .AGENTS.md.<ts>.bak + 合并入根
/root/xxx/configure/skills    散落 skill 归集: init/tag → /root/xxx/.opencode/skills/ (原位置保留)
/root/xxx/snsc             CODEX.md → .CODEX.md.2026-07-29-11-37-27.bak; AGENTS.md 更新

注意事项

• 先只读后写入（两阶段）：阶段 A 不改动任何文件；重命名统一放在阶段 B 最后批量执行；
• 所有归档/归集均为复制优先，先完整读取再重命名，防信息丢失；
• 不确定（外来文件夹判定、是否 agent 生成、生成技能的归属）时先询问用户（所有不确定点一次全部列出，不逐次追问），不臆断；
• 幂等：已归档（*.bak）与已归集内容不再处理，重复运行应输出"无变更"；
• 全局配置目录（~/.claude、~/.codex 等）只参考、不重命名；
• 本次改动按公共 Git 契约检查，未经明确要求不自动提交或推送；涉及 git 跟踪文件的重命名与删除仍须遵守用户授权；