---
name: config-migrate
description: 盘点、规划并迁移项目级或用户级的 Skills、Rules、MCP、Agents、Hooks 和 Commands 配置；适用于 Claude、Codex、Cursor、Trae、ZCode、Kimi 等开发工具之间的配置迁移。
---

# 工程配置迁移

## 目标

这个技能用于把当前环境中的工程化配置做系统盘点，并迁移为目标平台支持的结构。重点不是机械复制目录，而是：

- 识别当前项目级与用户级的工程化资源
- 按 `skills`、`rules`、`mcp`、`agents`、`hooks`、`commands`、`scripts/templates/docs` 分类
- 根据目标平台规范判断哪些能直接迁移、哪些要转换、哪些不能迁移
- 先给出实施方案并征求用户确认，再执行实际改动

## 命令约定

默认按以下方式理解用户输入：

```text
/config-migrate [target-platform] [migration-scope]
```

参数说明：

- `target-platform`：目标平台，例如 `claude`、`codex`、`cursor`、`trae`、`zcode`、`kimi`
- `migration-scope`：迁移范围，例如 `all`、`auto`、`skills`、`mcp+skills`、`rules+commands`

参数处理规则：

1. 如果用户显式给出参数，直接解析。
2. 如果用户未给出参数，先从当前上下文、工作区现状、用户最近表述中推断。
3. 推断结果必须向用户确认。
4. 如果无法可靠推断，先主动询问用户，不要跳过确认。

## 先看配套规范

开始规划前，优先查看同目录 `references/` 下已有目标平台规范：

- `references/claude-spec.md`
- `references/codex-spec.md`
- `references/cursor-spec.md`
- `references/trae-spec.md`
- `references/zcode-spec.md`
- `references/kimi-spec.md`

如果目标平台不在现有规范中：

1. 发起子代理调查目标平台。
2. 优先查官方文档、已安装技能、现有仓库资料。
3. 必要时联网搜索公开文档。
4. 产出一个与现有规范相同格式的 `<platform>-spec.md` 草案。
5. 如果仍找不到足够可信的规范，停止迁移并明确告知用户“当前无法安全转换”。

## 执行原则

- 先盘点，后规划，再实施，不要跳步。
- 先确认目标平台与迁移范围，再动文件。
- 任何不确定映射都进入“需确认项”，不要臆造字段。
- 兼容性风险要在实施前说清楚，例如 hooks、rules、agents 的平台差异。
- 如果用户只想看方案，不做改动，就停在方案和 TODO 阶段。
- 默认要求：先分析和出方案，用户确认后才开始真正转换。

## 标准流程

### 第 1 步：解析目标平台与范围

输出一份简短的参数结论：

- 目标平台
- 迁移范围
- 是否允许真实改动文件
- 是否需要补充调查目标平台规范

### 第 2 步：发起盘点子代理

必须发起一个子代理，扫描以下两层范围：

- 当前项目根目录
- 用户级目录

重点摸排一切常见以 `.` 开头的工程化目录，例如：

- `.claude`
- `.agents`
- `.codex`
- `.trae`
- `.cursor`
- `.zcode`
- `.kimi`
- `.claude-plugin`
- `.codex-plugin`
- `.zcode-plugin`
- 其他明显属于 agent 工程化配置的隐藏目录

盘点子代理的目标：

1. 列出发现到的目录和关键文件。
2. 识别其中的 `skills`、`rules`、`mcp`、`agents`、`hooks`、`commands`。
3. 额外识别 `scripts`、`templates`、`docs` 等辅助资源。
4. 将盘点结果落盘为清单文档。
5. 返回文档路径与摘要，而不是只回一段口头描述。

清单文档至少包含：

- 扫描范围
- 发现的目录
- 资源分类结果
- 同名冲突
- 疑似非标准格式资源
- 可直接迁移项
- 需转换项
- 需人工确认项

### 第 3 步：读取目标平台规范

如果目标平台已有规范文件：

- 直接读取对应 `references/<platform>-spec.md`

如果目标平台没有规范文件：

- 发起子代理补齐规范调查
- 必须输出项目级与用户级的落点、资源能力矩阵、兼容限制

### 第 4 步：判断是否可迁移

基于盘点结果与平台规范，把资源分为四类：

- `copy`：可直接复制或轻微调整
- `transform`：需要目录、frontmatter、字段、协议转换
- `rewrite`：需要重写结构或运行协议
- `blocked`：目标平台无对等能力，当前不能安全迁移

特别关注以下高风险资源：

- `hooks`
- `rules`
- `agents`
- `mcp`
- `commands`

### 第 5 步：输出实施方案并请求确认

在任何真实改动前，先给用户一份方案，至少包含：

- 迁移范围
- 来源目录与目标目录
- 将要改动的文件类型
- 每类资源的处理策略
- 兼容性问题与规避方式
- 无法自动迁移的内容
- 用户需要确认的决策点

没有用户确认，不要开始实施。

### 第 6 步：编写 TODO 清单

在用户确认实施后，输出详细 TODO，至少覆盖：

- 创建目标目录
- 迁移或改写各类资源
- 生成必要的规范文件或模板文件
- 校验迁移后结构
- 汇总结果与剩余风险

### 第 7 步：实施转换

实施时遵守以下顺序：

1. 创建目标目录骨架
2. 迁移静态资源：`skills`、`rules`、`commands`
3. 迁移辅助资源：`scripts`、`templates`、`docs`
4. 迁移结构敏感资源：`mcp`、`hooks`
5. 处理 `agents` 与平台专属角色定义
6. 更新或新增必要清单、说明和占位模板

实施要求：

- 优先保留原始语义和命名
- 仅在目标平台规范要求时做结构改写
- 对密钥、Token、路径等敏感值使用占位符
- 不要删除来源配置，除非用户明确要求

### 第 8 步：校验结果

校验必须覆盖：

- 目录结构是否符合目标平台规范
- 核心文件是否存在
- Markdown / JSON / TOML 等格式是否有效
- rules 的头部字段是否保留完整
- hooks / mcp 的关键字段是否符合目标平台要求
- 迁移范围外的内容没有被误改

如果存在已知偏差，必须在结果中明确列出。

### 第 9 步：汇报结果

最终汇报至少包含：

1. 盘点清单文档路径
2. 实际迁移到的目标路径
3. 已完成项
4. 已转换项
5. 被拦截项
6. 校验结果
7. 剩余风险与人工后续动作

## 平台差异处理规则

### Skills

- 目标平台原生支持 `SKILL.md` 时，优先保留目录型 skill 结构
- 目标平台不支持时，评估是否可转为 `agents`、`commands` 或文档资产

### Rules

- 只有当目标平台存在“长期规则 / 指令文件 / policies”这一对等能力时，才迁移为规则
- 若目标平台没有独立 rule 机制，则评估改写为 `AGENTS.md`、系统指令文档或 skill 内约束

### Commands

- 若目标平台支持 markdown 命令或 slash command，则迁入命令目录
- 若不支持独立命令，则评估合并进 skill 或 agent

### Hooks

- 不同平台的 hooks 协议差异最大，默认视为 `transform` 或 `rewrite`
- 不要把一个平台的 hook 配置文件原样复制到另一个平台

### MCP

- 优先保留 server 定义、启动命令、参数和环境变量结构
- 平台只要支持 MCP，就应尽量迁移
- 平台若不支持项目级 MCP，要明确说明只能迁到用户级

### Agents

- 如果目标平台支持可选 Agent/角色定义，则按其原生格式迁移
- 如果不支持独立 Agent，评估改写为 Skill、规则文档或说明文档

## 未知目标平台调查要求

当用户指定未知平台，例如 `Pi-agent`：

1. 先回顾已有知识与仓库材料。
2. 再发起子代理调查官方文档和公开资料。
3. 调查结论必须包含：
   - 项目级目录
   - 用户级目录
   - 支持的资源类型
   - 不支持的资源类型
   - 最小可用目录结构
   - 迁移限制
4. 找不到可信规范时，明确阻断，不要生成伪规范。

## 子代理返回格式要求

盘点类子代理返回：

- 清单文档绝对路径
- 扫描摘要
- 资源分类统计
- 冲突项
- 风险项

规范调查类子代理返回：

- 规范文档绝对路径或引用来源
- 项目级 / 用户级目录结论
- 能力矩阵
- 迁移限制
- 可信度说明

## 建议输出模板

### 方案阶段

```text
目标平台:
迁移范围:
来源目录:
目标目录:
资源处理策略:
兼容性风险:
阻断项:
待确认项:
```

### 结果阶段

```text
盘点清单:
新增文件:
转换文件:
校验结果:
阻断项:
后续建议:
```

## 快速检查清单

- [ ] 已确认目标平台
- [ ] 已确认迁移范围
- [ ] 已发起子代理完成项目级与用户级盘点
- [ ] 已生成盘点清单文档并拿到路径
- [ ] 已读取目标平台规范
- [ ] 已识别 `copy/transform/rewrite/blocked`
- [ ] 已在实施前向用户给出方案并获得确认
- [ ] 已输出 TODO 清单
- [ ] 已执行迁移
- [ ] 已完成结构与格式校验
- [ ] 已汇报结果与剩余风险

## 触发示例

- “用 `/config-migrate trae all` 扫描并迁移当前工程化配置到 Trae”
- “帮我把这个项目里的 `.claude`、`.codex` 和 `.cursor` 配置转成 ZCode 支持的结构”
- “先盘点当前环境，再告诉我这些 skills、hooks、mcp 能不能迁到 Kimi”
- “把迁移范围限定为 `skills+mcp`，先出方案，我确认后再改”
- “目标平台是 `Pi-agent`，如果没有规范先帮我调研”