copilot-agent-to-codex

name	copilot-agent-to-codex
description	將 GitHub Copilot custom agents（.agent.md）轉換為 Codex custom agents（.toml），包含流程指引、欄位映射範本與批次轉換腳本。

Copilot Agent -> Codex Agent 轉換 Skill

何時使用

• 你有 GitHub Copilot custom agents（通常在 .github/agents/*.agent.md）
• 你要轉成 Codex custom agents（通常在 .codex/agents/*.toml）
• 你希望批次轉換，且不覆蓋既有目標檔案

觸發詞（建議）

• convert github copilot agents to codex agents
• 把 .agent.md 轉成 codex .toml
• copilot-agent-to-codex

輸入與輸出

• 預設來源目錄：.github/agents
• 預設目標目錄：.codex/agents
• 來源檔案：*.agent.md
• 輸出檔案：<name>.toml

衝突策略：

• 若 <name>.toml 已存在，不覆蓋，改輸出 <name>.toml.new1、.new2 依序遞增

欄位映射規則

• frontmatter name -> TOML name
• frontmatter description -> TOML description（必填）
• frontmatter 下方 Markdown body -> TOML developer_instructions（必填）
• frontmatter tools：不映射到 TOML（由 instructions 與 parent session 控制）

備註：

• 若 name 缺失，回退使用來源檔名 stem（去掉 .agent.md）
• 不主動寫入 model、sandbox_mode（沿用 parent）

執行方式

1. Dry-run（先看結果，不寫檔）：

python3 .agents/skills/copilot-agent-to-codex/scripts/convert_agents.py --dry-run

2. 實際寫檔：

python3 .agents/skills/copilot-agent-to-codex/scripts/convert_agents.py

3. 指定來源/目標目錄：

python3 .agents/skills/copilot-agent-to-codex/scripts/convert_agents.py --src path/to/src --dst path/to/dst

4. 嚴格模式（任何 failed 直接非 0 exit）：

python3 .agents/skills/copilot-agent-to-codex/scripts/convert_agents.py --strict

輸出報表格式

腳本會輸出四類統計與清單：

• created
• conflict_new
• skipped
• failed

每筆都含：src、dst、msg

錯誤處理

• description 缺失 -> failed
• body 空內容 -> failed
• frontmatter 格式不合法或不存在 -> failed
• 來源目錄不存在 -> failed
• 來源目錄沒有 .agent.md -> skipped

驗證步驟

1. 確認輸出 TOML 語法可解析：

python3 - <<'PY'
import glob, tomllib
for p in glob.glob('.codex/agents/*.toml'):
    with open(p, 'rb') as f:
        tomllib.load(f)
print('OK')
PY

2. 確認每個輸出有必填鍵：

• name
• description
• developer_instructions

模板檔案

• templates/copilot-agent.example.md
• templates/codex-agent.example.toml