no-problem-dev/deploy-to-codex

Deploy to Codex — Claude Code → Codex CLI 変換

Claude Code プラグインマーケットプレイスのスキル・エージェントを Codex CLI 互換形式に変換し、.agents/skills/ と AGENTS.md を自動生成する。

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

---

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

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

---

Phase 1: Discovery — マーケットプレイス読み込み

1. リポジトリルートの .claude-plugin/marketplace.json を Read で読む
2. plugins[] 配列から各プラグインの source パスを解決
3. 各プラグインの {source}/.claude-plugin/plugin.json を Read で読む
4. メタデータを収集: name, version, description, skills, agents

エラー時: marketplace.json が見つからない場合は「このリポジトリは Claude Code プラグインマーケットプレイスではありません」と通知して終了。

---

Phase 2: Scan — コンポーネント列挙

各プラグインについて:

1. スキル: {source}/skills/*/SKILL.md を Glob で列挙
2. エージェント: {source}/agents/*.md を Glob で列挙
3. 非ポータブル: 以下を存在チェックし記録（変換対象外）
   • {source}/hooks/ — hooks
   • {source}/commands/ — commands
   • {source}/rules/ — rules
   • {source}/contexts/ — contexts

全コンポーネントをリスト化する。

---

Phase 3: 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

エージェント分類

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

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

---

Phase 4: Transform — SKILL.md 変換

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

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

削除するフィールド:

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

保持するフィールド:

• name
• description

4b. ボディ変換

全分類共通:

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

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

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

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

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

4c. ヘッダー追加

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

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

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

---

Phase 5: Agent Conversion — エージェント → スキル変換

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

変換手順:

1. エージェントのフロントマターから以下を 削除:
   • tools
   • model
2. 以下を 保持:
   • name
   • description
3. ボディはそのまま保持（CLI コマンド手順はそのまま使える）
4. フロントマターの上に AUTO-GENERATED ヘッダーを追加

変換対象の判定基準:

• エージェントの tools に Bash が含まれている
• ボディに MCP 専用ツール参照がない
• ボディに具体的な CLI コマンド（xcodebuild, swift, go, npm 等）が含まれている

---

Phase 6: Generation — ファイル出力

1. .agents/skills/ ディレクトリを作成（存在しない場合）
2. 変換済みスキルを .agents/skills/{skill-name}/SKILL.md に Write で出力

命名規則:

• 基本: スキル名をそのまま使用（例: ios-maintenance → .agents/skills/ios-maintenance/SKILL.md）
• 衝突時: {plugin-name}--{skill-name} プレフィックス（例: ios-dev--ios-maintenance）
  • 衝突判定: 異なるプラグインに同名のスキルが存在する場合
• エージェント由来: agent--{agent-name} プレフィックス（例: agent--ios-build-runner）

DELEGATION_ONLY スキルはスキップ:

ファイルを生成せず、Phase 7 の「非対応」セクションに記録する。

---

Phase 7: AGENTS.md Generation

リポジトリルートに .agents/AGENTS.md を生成する。

テンプレート:

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

# Codex CLI Skills

このリポジトリの Claude Code プラグインから自動変換された Codex CLI 互換スキルです。

> **Note:** このファイルと `.agents/skills/` は `deploy-to-codex` により自動生成されています。
> 手動編集は次回実行時に上書きされます。

## 利用方法

Codex CLI でスキルを使用するには:

$skill-name

## 利用可能スキル

| スキル | 元プラグイン | 互換性 | 説明 |
|--------|-------------|--------|------|
{PORTABLE/PARTIAL スキルを1行ずつ出力}

### 互換性レベル

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

## エージェント変換

| スキル名 | 元エージェント | 元プラグイン | 説明 |
|---------|---------------|-------------|------|
{変換されたエージェントを1行ずつ出力}

## Codex CLI 非対応コンポーネント

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

### スキップされたスキル（DELEGATION_ONLY）

| スキル | 元プラグイン | 理由 |
|--------|-------------|------|
{DELEGATION_ONLY スキルを1行ずつ出力}

### 非ポータブルコンポーネント

| 種別 | プラグイン | パス |
|------|----------|------|
{hooks, commands, rules, contexts を1行ずつ出力}

## フル機能を利用するには

全機能を利用するには Claude Code でプラグインをインストールしてください:

```bash
claude plugins add {marketplace-url}

生成統計

• 生成日時: {YYYY-MM-DD HH:mm}
• PORTABLE スキル: {count}
• PARTIAL スキル: {count}
• MCP_ONLY スキル: {count}
• エージェント変換: {count}
• スキップ（DELEGATION_ONLY）: {count}
• 非ポータブルコンポーネント: {count}

---

### Phase 8: Metadata — メタデータ出力

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

```json
{
  "generator": "deploy-to-codex",
  "version": "1.0.0",
  "generated_at": "{ISO 8601 timestamp}",
  "source_marketplace": ".claude-plugin/marketplace.json",
  "stats": {
    "plugins_scanned": 0,
    "skills_portable": 0,
    "skills_partial": 0,
    "skills_mcp_only": 0,
    "skills_delegation_only": 0,
    "agents_converted": 0,
    "non_portable_components": 0
  },
  "files_generated": [
    ".agents/skills/{name}/SKILL.md",
    "..."
  ],
  "checksum": "{SHA-256 of sorted file list + content hashes}"
}

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

---

実行後レポート

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

## deploy-to-codex 完了

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

### 出力
- .agents/skills/ — {total} スキル生成
- .agents/AGENTS.md — カタログ生成
- .agents/.codex-deploy-metadata.json — メタデータ記録

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