no-problem-dev/codex-export

codex-export — .claude/ プロジェクト → Codex CLI 変換

.claude/ ディレクトリを持つ任意のプロジェクトから、Codex CLI 互換の .agents/ を自動生成する。

SSOT 原則: Claude Code 側のスキル・コンテキストが常に正（Single Source of Truth）。 このスキルは読み取り専用の変換を行い、元ファイルを変更しない。

deploy-to-codex との違い: deploy-to-codex はプラグインマーケットプレイス（marketplace.json）が対象。 codex-export は通常のプロジェクト（.claude/ を持つリポジトリ）が対象。

---

実行フロー（6 フェーズ）

以下のフェーズを順番に実行する。各フェーズの結果を変数として保持し、後続フェーズで利用する。

---

Phase 1: Scan — .claude/ スキャン

1. プロジェクトルートで .claude/ の存在を確認
2. .claude/skills/*/SKILL.md を Glob で列挙
3. .claude/agents/*.md を Glob で列挙
4. .claude/contexts/*.md を Glob で列挙
5. .claude/hooks/, .claude/settings.json の存在を確認（非ポータブル記録用）

エラー: .claude/ が存在しない → 「このリポジトリに .claude/ ディレクトリがありません」と通知して終了。

自己除外: codex-export スキル自身および deploy-to-codex スキルは変換対象外とする。プラグイン由来のスキル（.claude/skills/ 以外に存在するスキル）も除外する。

---

Phase 2: Classification — 互換性分類

各 SKILL.md のボディを Read して以下のパターンで分類する。

検出パターン

MCP 参照パターン（正規表現）:

BuildProject|RenderPreview|ExecuteSnippet|XcodeList|RunAllTests|RunSomeTests|GetBuildLog|DocumentationSearch|mcp__|ToolSearch.*mcp

Task/委譲参照パターン:

Task\(|subagent_type|サブエージェント.*委譲|エージェントに委譲|サブエージェント経由

CLI フォールバックパターン:

CLI フォールバック|フォールバック.*CLI|xcodebuild|swift build|swift test|bash|Bash

分類ロジック

IF MCP参照なし AND Task参照なし:
  → PORTABLE
ELIF MCP参照あり AND CLIフォールバックあり:
  → PARTIAL
ELIF MCP参照あり AND CLIフォールバックなし:
  → MCP_ONLY
ELIF Task参照が主体（MCP参照なしでTask参照あり）:
  → DELEGATION_ONLY

エージェント分類（.claude/agents/ に存在する場合）

エージェント .md ファイルも同様に分類:

• tools フロントマターに Bash を含む → CLI 実行可能 → PORTABLE として変換候補
• MCP ツール参照のみ → MCP_ONLY
• 主に他エージェントを呼ぶ → DELEGATION_ONLY

---

Phase 3: Transform — SKILL.md 変換

分類に応じて変換を行う。

3a. フロントマター変換

削除するフィールド:

• allowed-tools
• user-invocable
• model
• disable-model-invocation
• context
• argument-hint

保持するフィールド:

• name
• description

3b. ボディ変換

全分類共通:

• スキル相互参照の置換: /skill-name → $skill-name（行頭または文中のスラッシュコマンド記法を $ 記法に）
  • 対象: /morning, /daily-log, /weekly 等の具体的スキル名参照
  • 非対象: /path/to/file のようなファイルパスは置換しない（スキル名は小文字+ハイフンのみで構成）

PARTIAL スキルの場合: MCP セクション（### MCP で始まるセクション、または MCP ツール呼び出しを含むコードブロック）の直前に以下を挿入:

> **Codex CLI Note:** 以下の MCP セクションは Codex CLI では利用できません。CLI フォールバック手順を使用してください。

MCP_ONLY スキルの場合: ファイル先頭（フロントマターの直後）に警告バナーを追加:

> **WARNING: このスキルは MCP サーバー専用です。Codex CLI では利用できません。参照用としてのみ含まれています。**

3c. エージェント変換（.claude/agents/ に存在する場合）

PORTABLE と分類されたエージェント .md をスキルに変換:

1. フロントマターから tools, model を 削除
2. name, description を 保持
3. ボディはそのまま保持
4. agent--{name} プレフィックスで出力

3d. ヘッダー追加

変換後の SKILL.md のフロントマター --- 閉じの直後（ボディの先頭）に以下を追加:

<!-- AUTO-GENERATED by codex-export | Source: {relative-path-from-project-root} | {YYYY-MM-DD} -->

重要: Codex CLI は --- が1行目に必須。AUTO-GENERATED コメントをフロントマターの前に置くとパースエラーになる。必ずフロントマターの後に配置すること。

---

Phase 4: Context Integration — コンテキスト統合

.claude/contexts/*.md の内容を AGENTS.md に統合する。

1. 各コンテキストファイルを Read
2. gitignore 対象の判別: ファイル名に local を含むもの（例: local-env.md）は内容を含めず、存在のみ記録する
3. 要約化: 各コンテキストの先頭 50 行を取得。50 行を超える場合は「→ 全文: .claude/contexts/{name}.md」のリンクを付記
4. AGENTS.md の「Project Context」セクションに配置

---

Phase 5: Generation — ファイル出力

出力先: .agents/

.agents/
├── AGENTS.md                       # プロジェクトガイド + コンテキスト要約 + スキル一覧
├── .codex-export-metadata.json     # メタデータ
└── skills/
    ├── {skill-name}/SKILL.md       # 変換済みスキル
    └── agent--{name}/SKILL.md      # エージェント変換（存在する場合）

1. .agents/skills/ ディレクトリを作成（既存の場合はクリーンアップ: 古いファイルを削除してから再生成）
2. 変換済みスキルを .agents/skills/{skill-name}/SKILL.md に Write で出力
3. DELEGATION_ONLY スキルはファイル生成をスキップし、AGENTS.md に記載のみ

AGENTS.md テンプレート:

<!-- AUTO-GENERATED by codex-export | {YYYY-MM-DD} -->

# {project-name}

> このファイルは codex-export により .claude/ から自動生成されています。
> 手動編集は次回実行時に上書きされます。

## Project Context

### {context-name}
{context の先頭 50 行、または全文が 50 行以下ならそのまま}
→ 全文: `.claude/contexts/{name}.md`

（※ gitignore 対象のコンテキストは「存在するが内容は非公開」として記載）

## Available Skills

| スキル | 互換性 | 説明 |
|--------|--------|------|
{PORTABLE/PARTIAL/MCP_ONLY スキルを1行ずつ出力}

### 互換性レベル

- **PORTABLE**: 完全互換。そのまま利用可能
- **PARTIAL**: 一部機能が MCP 依存。CLI フォールバック手順を利用
- **MCP_ONLY**: 参照用。Codex CLI では実行不可

## Agent Conversions

| スキル名 | 元エージェント | 説明 |
|---------|---------------|------|
{変換されたエージェントを1行ずつ出力。なければセクション省略}

## Non-portable Components

以下のコンポーネントは Claude Code 固有機能に依存するため、Codex CLI では利用できません。

| 種別 | パス | 備考 |
|------|------|------|
{hooks, settings, DELEGATION_ONLY スキル等を1行ずつ出力}

## Full Features

全機能は Claude Code で利用可能:

cd {project-path} && claude

## Stats
- Generated: {YYYY-MM-DD HH:mm}
- Skills: {portable_count} portable, {partial_count} partial, {mcp_only_count} mcp_only
- Agents converted: {count}
- Contexts integrated: {count}
- Skipped (DELEGATION_ONLY): {count}
- Non-portable components: {count}

---

Phase 6: Metadata — メタデータ出力

.agents/.codex-export-metadata.json に以下を Write で出力:

{
  "generator": "codex-export",
  "version": "1.0.0",
  "generated_at": "{ISO 8601 timestamp}",
  "source": ".claude/",
  "stats": {
    "skills_portable": 0,
    "skills_partial": 0,
    "skills_mcp_only": 0,
    "skills_delegation_only": 0,
    "agents_converted": 0,
    "contexts_integrated": 0,
    "non_portable_components": 0
  },
  "files_generated": [
    ".agents/skills/{name}/SKILL.md",
    "..."
  ],
  "checksum": "{SHA-256 of sorted file list + content hashes}"
}

べき等性: 次回実行時にこのメタデータを読み、ソースファイルの更新日時やチェックサムと比較して変更がなければスキップできる。初回実行時はフル生成する。

---

実行後レポート

全フェーズ完了後、ユーザーに以下のサマリーを表示する:

## codex-export 完了

### 生成結果
- PORTABLE: {count} スキル
- PARTIAL: {count} スキル（MCP 注記付き）
- MCP_ONLY: {count} スキル（警告バナー付き）
- エージェント変換: {count}
- コンテキスト統合: {count}
- スキップ: {count}（DELEGATION_ONLY）

### 出力
- .agents/skills/ — {total} スキル生成
- .agents/AGENTS.md — プロジェクトガイド生成
- .agents/.codex-export-metadata.json — メタデータ記録

### 次のステップ
1. 生成されたスキルを確認: `ls .agents/skills/`
2. AGENTS.md を確認: `cat .agents/AGENTS.md`
3. 変更をコミット: `git add .agents/ && git commit -m "codex: export .claude/ skills for Codex CLI"`