Codex CLI Bridge スキル

目的

このスキルは、Claude Code と OpenAI の Codex CLI の間に包括的なブリッジを作成し、以下を通じてシームレスな相互運用性を実現します：

1. ドキュメント翻訳: CLAUDE.md → AGENTS.md を変換（参照ベース、ファイル重複なし）
2. 実行ヘルパー: Codex CLI コマンド用の Python ラッパー（常に codex exec を使用）
3. スキルドキュメント: Claude スキルを Codex CLI ユーザーがアクセス可能にする

主要機能

1. CLAUDE.md → AGENTS.md 生成

• CLAUDE.md とプロジェクト構造を解析
• .claude/skills/、.claude/agents/、documentation/ フォルダをスキャン
• ファイルパス参照を含む包括的な AGENTS.md を生成
• 参照ベース: ファイル重複なし、既存ファイルへのリンクのみ
• スキルを最も関連性の高い使用方法で文書化（bash スクリプト vs プロンプト参照）

2. 安全メカニズム

• Codex CLI インストール自動チェック（codex --version）
• CLAUDE.md が見つからない場合は /init 自動実行（ユーザー通知付き）
• 認証と環境の検証
• ユーザーフレンドリーなエラーメッセージ

3. Codex CLI 実行ヘルパー

• exec_analysis() - 読み取り専用分析タスク（gpt-5、読み取り専用サンドボックス）
• exec_edit() - コード編集タスク（gpt-5-codex、ワークスペース書き込み）
• exec_with_search() - Web 検索機能付きタスク
• resume_session() - 最後の Codex セッションを継続
• 常に codex exec を使用（plain codex は使用しない - Claude Code に重要）

4. Codex CLI 用スキルドキュメント

• プロンプトのみのスキル: Codex プロンプトでの参照方法を表示
• 機能スキル: Python スクリプトを直接実行する方法を表示
• 複雑なスキル: 両方の方法を表示
• 適切な codex exec コマンド構文を含める
• モデル選択ガイダンス（gpt-5 vs gpt-5-codex）

入力要件

AGENTS.md 生成の場合

{
  "action": "generate-agents-md",
  "project_root": "/path/to/project",
  "options": {
    "validate_codex": true,
    "auto_init": true,
    "include_mcp": true,
    "skill_detail_level": "relevant"
  }
}

Codex 実行の場合

{
  "action": "codex-exec",
  "task_type": "analysis|edit|search",
  "prompt": "Your task description",
  "model": "gpt-5|gpt-5-codex",
  "sandbox": "read-only|workspace-write|danger-full-access"
}

出力形式

AGENTS.md 構造

# AGENTS.md

## プロジェクト概要
[CLAUDE.md から]

## 利用可能なスキル
### スキル名
**場所**: `path/to/skill/`
**Codex CLI から使用**: [最も関連性の高い方法]

## ワークフローパターン
[スラッシュコマンド → Codex 相当機能]

## MCP インテグレーション
[MCP サーバー参照]

## コマンドリファレンス
| Claude Code | Codex CLI |
|-------------|-----------|
[マッピング]

実行ヘルパー出力

{
  "status": "success|error",
  "output": "Command output",
  "session_id": "uuid",
  "model_used": "gpt-5|gpt-5-codex",
  "command": "codex exec ..."
}

Python スクリプト

safety_mechanism.py

• Codex CLI インストールチェック
• CLAUDE.md の存在を検証（見つからない場合は /init 自動実行）
• 環境検証
• ユーザー通知

claude_parser.py

• CLAUDE.md セクションを解析
• スキル、エージェント、コマンドをスキャン
• 品質ゲートと MCP 設定を抽出
• ファイルパスのみを返す（コンテンツ重複なし）

project_analyzer.py

• プロジェクト構造を自動検出
• すべての Claude Code アセットを発見
• プロジェクトメタデータを生成
• 参照マップを構築

agents_md_generator.py

• テンプレートベースの AGENTS.md 生成
• ファイルパス参照（重複なし）
• スキルドキュメント（最も関連性の高い方法）
• ワークフロー翻訳（Claude → Codex）

skill_documenter.py

• Codex CLI ユーザー向けのスキルドキュメント
• スキルタイプごとに最も関連性の高い使用方法を決定
• Python スクリプト用の bash 例を生成
• Codex プロンプトテンプレートを作成

codex_executor.py

• Codex CLI コマンド用の Python ラッパー
• インテリジェントなモデル選択（gpt-5 vs gpt-5-codex）
• サンドボックスモードヘルパー
• セッション管理
• 常に codex exec を使用

使用例

例 1: AGENTS.md を生成

ユーザープロンプト:

このプロジェクトの AGENTS.md を生成してください

処理内容:

1. 安全メカニズムが Codex CLI がインストールされていることを確認
2. CLAUDE.md が存在することを確認（見つからない場合は /init を自動実行）
3. CLAUDE.md とプロジェクト構造を解析
4. ファイル参照を含む AGENTS.md を生成
5. すべてのスキルを最も関連性の高い使用方法で文書化

出力: プロジェクトルートに完全な AGENTS.md ファイル

---

例 2: Codex 分析タスクを実行

ユーザープロンプト:

このコードベースのセキュリティ脆弱性を Codex で分析してください

処理内容:

from codex_executor import CodexExecutor

executor = CodexExecutor()
result = executor.exec_analysis(
    "Analyze this codebase for security vulnerabilities",
    model="gpt-5"
)

実行:

codex exec -m gpt-5 -s read-only \
  -c model_reasoning_effort=high \
  "Analyze this codebase for security vulnerabilities"

---

例 3: Codex コード編集を実行

ユーザープロンプト:

main.py を Codex でリファクタリングしてより良い非同期パターンにしてください

処理内容:

executor = CodexExecutor()
result = executor.exec_edit(
    "Refactor main.py for better async patterns",
    model="gpt-5-codex"
)

実行:

codex exec -m gpt-5-codex -s workspace-write \
  -c model_reasoning_effort=high \
  "Refactor main.py for better async patterns"

---

例 4: Codex セッションを再開

ユーザープロンプト:

前の Codex セッションを続行してください

処理内容:

executor = CodexExecutor()
result = executor.resume_session()

実行:

codex exec resume --last

ベストプラクティス

AGENTS.md 生成の場合

1. CLAUDE.md があるプロジェクトで常に実行（または自動初期化で作成）
2. 最初に Codex CLI がインストールされていることを検証
3. スキルを最も関連性の高い方法で文書化（bash vs プロンプト）
4. 参照ベースのアプローチを使用（ファイル重複なし）

Codex 実行の場合

1. 常に codex exec を使用（Claude Code では plain codex を使用しない）
2. 正しいモデルを選択:
   • gpt-5: 一般的な推論、アーキテクチャ、分析
   • gpt-5-codex: コード編集、専門的なコーディングタスク
3. 正しいサンドボックスを選択:
   • read-only: 安全な分析（デフォルト）
   • workspace-write: ファイル修正
   • danger-full-access: ネットワークアクセス（めったに不要）
4. 必要に応じて検索を有効化（--search フラグ）

スキルドキュメントの場合

1. プロンプトのみのスキル: Codex プロンプトで参照
2. 機能スキル: Python スクリプトを直接実行
3. 複雑なスキル: 両方の方法を表示
4. 常に動作する例を提供

コマンド統合

このスキルは既存の Claude Code コマンドと統合します：

• /init: CLAUDE.md 作成後に AGENTS.md を自動生成
• /update-claude: CLAUDE.md が変更されたときに AGENTS.md を再生成
• /check-docs: AGENTS.md が存在し同期していることを検証
• /sync-agents-md: 手動で AGENTS.md を再生成
• /codex-exec <task>: codex_executor.py を使用するラッパー

インストール

前提条件

1. Codex CLI がインストール済み:

   codex --version  # v0.48.0 以上を表示すること
   

2. Codex が認証済み:

   codex login
   

3. Claude Code v1.0 以上

スキルをインストール

オプション 1: プロジェクトにコピー

cp -r generated-skills/codex-cli-bridge ~/.claude/skills/

オプション 2: このリポジトリから使用

# Claude Code がこのプロジェクトをロードするときにスキルが自動発見されます

トラブルシューティング

エラー: "Codex CLI not found"

解決策: Codex CLI をインストールして PATH に含まれていることを確認します

which codex  # パスを返すこと
codex --version  # 動作することを確認

エラー: "CLAUDE.md not found"

解決策: スキルが通知付きで自動的に /init を実行します。失敗する場合：

# 手動で /init を実行
/init

エラー: "stdout is not a terminal"

解決策: 常に codex exec を使用し、plain codex は使用しません

❌ codex -m gpt-5 "task"
✅ codex exec -m gpt-5 "task"

AGENTS.md が同期していない

解決策: 手動で再生成します

/sync-agents-md

リファレンス

• Codex CLI ドキュメント: openai-codex-cli-instructions.md
• Claude スキルドキュメント: claude-skills-instructions.md
• スキル例: claude-skills-examples/codex-cli-skill.md
• AGENTS.md 仕様: https://agents.md/

バージョン

v1.0.0 - 初回リリース（2025-10-30）

ライセンス

Apache 2.0

---

作成者: Claude Code Skills Factory 維持対象: クロスツールチーム協働（Claude Code ↔ Codex CLI） 同期状態: 参照ベースのブリッジ（単方向同期: CLAUDE.md → AGENTS.md）