工程配置遷移
目標
這個技能用於把當前環境中的工程化配置做系統盤點,並遷移為目標平台支援的結構。重點不是機械複製目錄,而是:
- 識別當前項目級與用戶級的工程化資源
- 按
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,如果沒有規範先幫我調研」