工程配置迁移
目标
这个技能用于把当前环境中的工程化配置做系统盘点,并迁移为目标平台支持的结构。重点不是机械复制目录,而是:
- 识别当前项目级与用户级的工程化资源
- 按
skills、rules、mcp、agents、hooks、commands、scripts/templates/docs分类 - 根据目标平台规范判断哪些能直接迁移、哪些要转换、哪些不能迁移
- 先给出实施方案并征求用户确认,再执行实际改动
命令约定
默认按以下方式理解用户输入:
/config-migrate [target-platform] [migration-scope]
参数说明:
target-platform:目标平台,例如claude、codex、cursor、trae、zcode、kimimigration-scope:迁移范围,例如all、auto、skills、mcp+skills、rules+commands
参数处理规则:
- 如果用户显式给出参数,直接解析。
- 如果用户未给出参数,先从当前上下文、工作区现状、用户最近表述中推断。
- 推断结果必须向用户确认。
- 如果无法可靠推断,先主动询问用户,不要跳过确认。
先看配套规范
开始规划前,优先查看同目录 references/ 下已有目标平台规范:
references/claude-spec.mdreferences/codex-spec.mdreferences/cursor-spec.mdreferences/trae-spec.mdreferences/zcode-spec.mdreferences/kimi-spec.md
如果目标平台不在现有规范中:
- 发起子代理调查目标平台。
- 优先查官方文档、已安装技能、现有仓库资料。
- 必要时联网搜索公开文档。
- 产出一个与现有规范相同格式的
<platform>-spec.md草案。 - 如果仍找不到足够可信的规范,停止迁移并明确告知用户“当前无法安全转换”。
执行原则
- 先盘点,后规划,再实施,不要跳步。
- 先确认目标平台与迁移范围,再动文件。
- 任何不确定映射都进入“需确认项”,不要臆造字段。
- 兼容性风险要在实施前说清楚,例如 hooks、rules、agents 的平台差异。
- 如果用户只想看方案,不做改动,就停在方案和 TODO 阶段。
- 默认要求:先分析和出方案,用户确认后才开始真正转换。
标准流程
第 1 步:解析目标平台与范围
输出一份简短的参数结论:
- 目标平台
- 迁移范围
- 是否允许真实改动文件
- 是否需要补充调查目标平台规范
第 2 步:发起盘点子代理
必须发起一个子代理,扫描以下两层范围:
- 当前项目根目录
- 用户级目录
重点摸排一切常见以 . 开头的工程化目录,例如:
.claude.agents.codex.trae.cursor.zcode.kimi.claude-plugin.codex-plugin.zcode-plugin- 其他明显属于 agent 工程化配置的隐藏目录
盘点子代理的目标:
- 列出发现到的目录和关键文件。
- 识别其中的
skills、rules、mcp、agents、hooks、commands。 - 额外识别
scripts、templates、docs等辅助资源。 - 将盘点结果落盘为清单文档。
- 返回文档路径与摘要,而不是只回一段口头描述。
清单文档至少包含:
- 扫描范围
- 发现的目录
- 资源分类结果
- 同名冲突
- 疑似非标准格式资源
- 可直接迁移项
- 需转换项
- 需人工确认项
第 3 步:读取目标平台规范
如果目标平台已有规范文件:
- 直接读取对应
references/<platform>-spec.md
如果目标平台没有规范文件:
- 发起子代理补齐规范调查
- 必须输出项目级与用户级的落点、资源能力矩阵、兼容限制
第 4 步:判断是否可迁移
基于盘点结果与平台规范,把资源分为四类:
copy:可直接复制或轻微调整transform:需要目录、frontmatter、字段、协议转换rewrite:需要重写结构或运行协议blocked:目标平台无对等能力,当前不能安全迁移
特别关注以下高风险资源:
hooksrulesagentsmcpcommands
第 5 步:输出实施方案并请求确认
在任何真实改动前,先给用户一份方案,至少包含:
- 迁移范围
- 来源目录与目标目录
- 将要改动的文件类型
- 每类资源的处理策略
- 兼容性问题与规避方式
- 无法自动迁移的内容
- 用户需要确认的决策点
没有用户确认,不要开始实施。
第 6 步:编写 TODO 清单
在用户确认实施后,输出详细 TODO,至少覆盖:
- 创建目标目录
- 迁移或改写各类资源
- 生成必要的规范文件或模板文件
- 校验迁移后结构
- 汇总结果与剩余风险
第 7 步:实施转换
实施时遵守以下顺序:
- 创建目标目录骨架
- 迁移静态资源:
skills、rules、commands - 迁移辅助资源:
scripts、templates、docs - 迁移结构敏感资源:
mcp、hooks - 处理
agents与平台专属角色定义 - 更新或新增必要清单、说明和占位模板
实施要求:
- 优先保留原始语义和命名
- 仅在目标平台规范要求时做结构改写
- 对密钥、Token、路径等敏感值使用占位符
- 不要删除来源配置,除非用户明确要求
第 8 步:校验结果
校验必须覆盖:
- 目录结构是否符合目标平台规范
- 核心文件是否存在
- Markdown / JSON / TOML 等格式是否有效
- rules 的头部字段是否保留完整
- hooks / mcp 的关键字段是否符合目标平台要求
- 迁移范围外的内容没有被误改
如果存在已知偏差,必须在结果中明确列出。
第 9 步:汇报结果
最终汇报至少包含:
- 盘点清单文档路径
- 实际迁移到的目标路径
- 已完成项
- 已转换项
- 被拦截项
- 校验结果
- 剩余风险与人工后续动作
平台差异处理规则
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:
- 先回顾已有知识与仓库材料。
- 再发起子代理调查官方文档和公开资料。
- 调查结论必须包含:
- 项目级目录
- 用户级目录
- 支持的资源类型
- 不支持的资源类型
- 最小可用目录结构
- 迁移限制
- 找不到可信规范时,明确阻断,不要生成伪规范。
子代理返回格式要求
盘点类子代理返回:
- 清单文档绝对路径
- 扫描摘要
- 资源分类统计
- 冲突项
- 风险项
规范调查类子代理返回:
- 规范文档绝对路径或引用来源
- 项目级 / 用户级目录结论
- 能力矩阵
- 迁移限制
- 可信度说明
建议输出模板
方案阶段
目标平台:
迁移范围:
来源目录:
目标目录:
资源处理策略:
兼容性风险:
阻断项:
待确认项:
结果阶段
盘点清单:
新增文件:
转换文件:
校验结果:
阻断项:
后续建议:
快速检查清单
- 已确认目标平台
- 已确认迁移范围
- 已发起子代理完成项目级与用户级盘点
- 已生成盘点清单文档并拿到路径
- 已读取目标平台规范
- 已识别
copy/transform/rewrite/blocked - 已在实施前向用户给出方案并获得确认
- 已输出 TODO 清单
- 已执行迁移
- 已完成结构与格式校验
- 已汇报结果与剩余风险
触发示例
- “用
/config-migrate trae all扫描并迁移当前工程化配置到 Trae” - “帮我把这个项目里的
.claude、.codex和.cursor配置转成 ZCode 支持的结构” - “先盘点当前环境,再告诉我这些 skills、hooks、mcp 能不能迁到 Kimi”
- “把迁移范围限定为
skills+mcp,先出方案,我确认后再改” - “目标平台是
Pi-agent,如果没有规范先帮我调研”