Claude to trae

Claude Code / Codex / ZCode -> Trae 工程化迁移指南

概述

这个技能用于把常见 AI 工程化目录迁移为 Trae 标准结构。目标不是简单复制文件，而是把源配置按 Trae 的目录、协议和职责重新落位，最终得到一套可直接被 Trae 识别和维护的工程文件。

本技能优先支持以下来源：

• .claude/
• .codex/
• .zcode/
• .agents/skills/

本技能输出的目标结构至少包括：

• .trae/skills/<name>/SKILL.md
• .trae/rules/**/*.md
• .trae/commands/**/*.md
• .trae/hooks.json
• .trae/mcp.json
• .agents/skills/<name>/SKILL.md

本技能的边界

• 管：工程化配置迁移、结构重组、协议转换、模板生成、校验清单、迁移诊断
• 不管：业务代码迁移、框架升级、依赖重构、功能重写

如果用户混合提出“配置迁移 + 业务改造”，先完成配置迁移规划，再把业务改造留给独立任务。

迁移策略

默认采用“混合策略”：

1. 先尽量保留源目录的命名、语义和边界。
2. 仅在 Trae 规范要求或明显更利于维护时，才做结构转换或语义重写。
3. 所有主动优化都要给出原因，不能默默改写。

迁移动作分为三类：

• 复制：格式与语义都可直接复用
• 转换：结构相近，但需要改目录、frontmatter、配置层级或调用方式
• 优化：在不改变原始意图的前提下，重组为更符合 Trae 的形式

目标目录总览

.trae/
├── skills/
│   └── <skill-name>/
│       └── SKILL.md
├── rules/
│   └── *.md
├── commands/
│   └── *.md
├── hooks.json
└── mcp.json

.agents/
└── skills/
    └── <skill-name>/
        └── SKILL.md

额外参考：

• 资源映射矩阵：references/source-to-trae-map.md
• Trae 目标制式：references/trae-target-spec.md
• 规则模板：templates/trae-rule-template.md
• Hook 模板：templates/trae-hooks-template.json
• MCP 模板：templates/trae-mcp-template.json
• 扫描脚本模板：scripts/inventory-source-configs.js
• 校验脚本模板：scripts/validate-trae-migration.js

源目录识别与优先级

扫描模式

优先支持两种模式：

1. 指定目录扫描
   • 用户明确给出源目录时，只扫描指定路径。
2. 默认常见目录扫描
   • 用户未指定时，按以下顺序扫描项目根：
   • .claude/
   • .codex/
   • .zcode/
   • .agents/skills/

优先级规则

如果同一能力在多个来源同时存在，优先级建议如下：

1. 用户明确指定的目录
2. 已被当前项目实际使用的目录
3. .claude/
4. .codex/
5. .zcode/
6. .agents/skills/

如果存在同名冲突，必须输出冲突清单，并说明：

• 哪些是完全重复
• 哪些是版本差异
• 哪些语义冲突需要用户确认

资源映射总规则

1. Skills

• 源 skills 优先迁移到 .trae/skills/
• 若目标希望跨工具共享，或源技能本身已经是通用 open-skill 结构，可改落到 .agents/skills/

2. Rules

• 源项目约束、规范说明、风格文档、团队约定，优先整理为 .trae/rules/**/*.md
• 规则文件必须保留 frontmatter，并满足 Trae 规则格式

3. Commands

• 源命令类 markdown 或 prompt 文件，迁移到 .trae/commands/**/*.md
• 目录嵌套不超过 3 层

4. Hooks

• 源 hook 脚本与配置不能只复制，必须一起迁移到 .trae/hooks.json 的结构
• 如需保留配套脚本，脚本路径和调用方式必须与目标工程一致

5. MCP

• 源 mcpServers、MCP 配置片段或工具服务器定义，迁移到 .trae/mcp.json
• 敏感信息统一改为占位值，并提示用户补全

6. Agents

采用双轨策略：

• 如果源 agent 更像“任务说明书 / 专业能力模块 / 触发型复用单元”，转为 .trae/skills/<name>/SKILL.md
• 如果源 agent 更像“跨工具共享技能”，转为 .agents/skills/<name>/SKILL.md

判定标准：

• 有明确的触发条件、能力边界、步骤说明，更像 skill -> .trae/skills/
• 主要目的是跨 Claude、Trae、Codex 等多工具共享 -> .agents/skills/
• 如果难以判断，先给出候选落点与判定理由，再请用户确认

各资源迁移规则

3.1 .claude

常见来源：

• .claude/skills/
• .claude/commands/
• .claude/hooks/
• .claude/settings.json
• .claude/agents/

迁移原则：

• skills：优先进入 .trae/skills/，必要时进入 .agents/skills/
• commands：迁移到 .trae/commands/
• hooks + settings.json：重组为 .trae/hooks.json
• mcpServers：迁移到 .trae/mcp.json
• agents：按双轨策略判断

3.2 .codex

常见来源：

• .codex/skills/
• .codex/hooks.json
• .codex/hooks/
• .codex/agents/

迁移原则：

• Codex 中部分命令可能被包装成 skill，不能机械复制到 .trae/skills/
• 需要先判断该文件本质是“命令”还是“技能”
• .codex/agents 若不是 markdown skill 结构，需要先做格式转换，再进入目标落点

3.3 .zcode

常见来源：

• .zcode/skills/
• .zcode/commands/
• .zcode/agents/
• .zcode/hooks/
• .zcode/config.json

迁移原则：

• 静态资源可以复用语义，但目录需改为 Trae 结构
• ZCode 的 hook 输出协议不能直接套进 Trae；Trae 的 SessionStart 和 UserPromptSubmit 支持纯文本输出，要按 Trae 规则改写
• .zcode/config.json 中的 MCP 与 hooks 配置要拆解后分别落入 .trae/mcp.json 和 .trae/hooks.json

3.4 .agents/skills

.agents/skills/ 本身就是跨工具共享层：

• 如果用户目标是“让 Trae 原生接管并做项目内定制”，可复制到 .trae/skills/
• 如果用户目标是“保留跨工具共享”，可保持在 .agents/skills/
• 如果需要同时保留共享版和 Trae 定制版，优先将原版保留在 .agents/skills/，再在 .trae/skills/ 放置覆盖版

高自动化执行流程

执行时按以下 6 步进行：

步骤 1：扫描资源清单

优先使用 scripts/inventory-source-configs.js 的逻辑，输出：

• 检测到的源目录
• 每类资源数量
• 同名冲突
• 可以直接复制的项目
• 需要转换的项目
• 需要人工确认的项目

步骤 2：建立迁移清单

按资源类型形成清单：

• skills
• rules
• commands
• hooks
• mcp
• agents
• templates/scripts

每一项都要标记迁移动作：

• copy
• transform
• optimize
• manual-review

步骤 3：创建目标目录骨架

按需要创建：

.trae/skills/
.trae/rules/
.trae/commands/
.trae/hooks.json
.trae/mcp.json
.agents/skills/

步骤 4：按类型迁移

迁移顺序建议：

1. skills
2. rules
3. commands
4. hooks
5. mcp
6. agents

原因：

• 先迁移静态结构
• 再迁移协议敏感项
• 最后处理需要判定的 agent 双轨落点

步骤 5：做结构校验

优先使用 scripts/validate-trae-migration.js 的逻辑检查：

• 目录是否完整
• 关键文件是否存在
• rules frontmatter 是否齐全
• hooks / mcp 配置文件是否存在
• agent 双轨结果是否都有明确说明

步骤 6：输出迁移报告

报告中至少包括：

• 已迁移项
• 已转换项
• 被优化项
• 需要用户确认项
• 无法自动迁移项
• 后续建议

Hook 迁移注意事项

这是最容易误迁移的部分。

必须记住的差异

• Trae 的 hook 配置文件是 .trae/hooks.json
• Windows 下 hook 默认在 PowerShell 环境中执行
• SessionStart 与 UserPromptSubmit 可以直接输出纯文本作为附加上下文
• 其他事件如果需要流程控制，应按 Trae 支持的 JSON 输出与退出码约定处理

迁移要求

• 不能把 .claude/settings.json 或 .zcode/config.json 原样复制为 .trae/hooks.json
• 必须拆出事件、matcher、命令、运行方式、输入输出预期
• 必须检查 shell 语法是否兼容 Windows PowerShell

Rules 迁移注意事项

规则来源

可从以下内容抽取规则：

• AGENTS.md
• 项目规范文档
• Hook 中的固定约束
• Skill 中长期稳定的项目要求

规则落地方式

• 全局长期约束 -> .trae/rules/*.md
• 模块级约束 -> 子目录下 .trae/rules/*.md
• 无法判断是否应长期生效 -> 先生成智能生效规则

规则模板约束

所有示例规则文件都必须保留：

---
alwaysApply: false
description: 当需要迁移并应用对应项目约束时
---

Commands 迁移注意事项

• Trae 项目命令目录为 .trae/commands
• 最多支持 3 层嵌套
• 命令文件应保留明确的用途与输出要求
• 若源文件本质是长篇操作指南，不要强行放进 commands，应考虑迁移为 skill 或 rule

MCP 迁移注意事项

• 项目级 MCP 配置应放入 .trae/mcp.json
• 源 mcpServers、server 定义、脚本启动命令需保留结构
• 所有密钥、Token、Access Key 都改为占位值
• 迁移完成后明确提醒用户替换真实配置

失败策略

遇到以下情况时，不要盲目继续：

1. 同名资源冲突

输出冲突矩阵，说明：

• 源路径
• 目标路径
• 差异类型
• 推荐保留方案

2. Agent 落点不明确

列出两种候选：

• .trae/skills/...
• .agents/skills/...

并说明为什么难以自动判断。

3. Hook 运行协议不明确

先保留最小安全版本：

• 事件
• matcher
• 命令
• 注释或说明

不要编造未验证的字段。

4. 源目录格式非标准

先做资源清点与分类，输出“无法自动迁移项”，再请求用户确认。

产出要求

执行本技能时，最终产出应包含：

1. 迁移前扫描结果
2. 资源映射表
3. 目标目录方案
4. 迁移执行结果
5. 校验结果
6. 未解决问题与后续建议

快速检查清单

• 已确认扫描范围是指定目录还是默认常见目录
• 已识别 .claude、.codex、.zcode、.agents/skills 中实际存在的来源
• 每类资源都已标记为复制、转换、优化或人工确认
• agents 已按双轨策略判断
• rules 已转换为符合 Trae 规范的 markdown 文件
• hooks 已重组成 .trae/hooks.json
• mcp 已重组成 .trae/mcp.json
• 已输出迁移报告与校验结果

触发示例

• “把这个项目的 .claude 工程化配置迁移到 Trae”
• “扫描 .claude 和 .codex，帮我生成 .trae 标准目录”
• “把 ZCode 的 hooks 和 mcp 配置改成 Trae 的标准文件”
• “帮我判断这些 agents 应该进 .trae/skills 还是 .agents/skills”
• “现有 Trae 配置很乱，按官方结构重组一下”