Claude Code プラグインを Codex CLI 互換に変換 - SKILL.md → .agents/skills/ + AGENTS.md 自動生成

version
1.0.0
GitHub stars
5

Install

/plugin install deploy-to-codex@no-problem-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add no-problem-dev/claude-code-plugins.

Contents

Discovered from source

Skills 2

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"`

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"`

Sponsors

Details

Marketplace
no-problem-dev/claude-code-plugins
Source
plugins/deploy-to-codex
Category
Tooling

More from no-problem-dev/claude-code-plugins

All 9