ln-004-agent-config-sync

パス： ファイルパス（shared/、references/、../ln-*）は skills リポジトリのルートを基準とします。CWD に見つからない場合は、この SKILL.md ディレクトリを探し、1 つ上の階層をリポジトリのルートとしてください。

エージェントの同期（スタンドアロンユーティリティ）

タイプ： スタンドアロンユーティリティ
カテゴリ： 0XX Shared

Claude Code（信頼できる唯一の情報源）から Gemini CLI および Codex CLI に、スキルと MCP サーバーの設定を同期します。スキルのシンボリックリンクを作成し、MCP 設定をコピー／変換します。

---

このスキルを使用するタイミング

• Claude Code の設定で MCP サーバーを追加または削除した後
• Claude Code に新しいプラグインをインストールした後
• Claude Code と併用して Gemini CLI または Codex CLI を初めてセットアップするとき
• すべてのエージェントを定期的に同期するとき

---

入力パラメーター

パラメーター	必須	デフォルト	説明
targets	いいえ	both	gemini、codex、または both
mode	いいえ	full	skills（シンボリックリンクのみ）、mcp（MCP のみ）、または full（両方）
dry_run	いいえ	false	実行せずに予定されている操作を表示

---

ワークフロー

Detect OS → Discover Configs → Sync Skills → Sync MCP → Report

フェーズ 0：OS の検出

確認項目	結果	影響
uname またはプラットフォーム	win32 / darwin / linux	ジャンクションとシンボリックリンクの選択
ホームディレクトリ	$HOME または $USERPROFILE	設定パス

OS 別のパス：

エージェント	Windows	macOS / Linux
Claude	%USERPROFILE%\.claude.json（優先）	~/.claude.json（優先）
Claude	%USERPROFILE%\.claude\settings.json（フォールバック）	~/.claude/settings.json（フォールバック）
Gemini	%USERPROFILE%\.gemini\settings.json	~/.gemini/settings.json
Codex	%USERPROFILE%\.codex\config.toml	~/.codex/config.toml

フェーズ 1：現在の状態を確認

1. Claude の設定を読み込む（両方のソースを確認して統合）：

   • ~/.claude.json を解析 → mcpServers ブロックを抽出（優先ソース、アプリ状態ファイル）
   • ~/.claude/settings.json を解析 → mcpServers ブロックを抽出（フォールバック、ユーザー設定ファイル）
   • 統合：サーバー名が同じ場合は優先ソースを優先
   • いずれにも mcpServers がない場合 → 「Claude に MCP サーバーが設定されていません」と警告し、MCP の同期をスキップ

2. 同期先の設定を読み込む（存在する場合）：

   • Gemini：~/.gemini/settings.json を解析 → 既存の mcpServers を抽出
   • Codex：~/.codex/config.toml を解析 → 既存の [mcp_servers.*] を抽出

3. インストール済みプラグインを検出：

   • ~/.claude/plugins/*/plugin.json に対して Glob を実行 → プラグインディレクトリを一覧表示
   • スキルリポジトリ自体がプラグインのソースかどうかも確認

4. 既存のシンボリックリンクを確認：

   • ~/.gemini/skills → 存在するか、リンク先はどこか
   • ~/.codex/skills → 存在するか、リンク先はどこか

5. 現在の状態を表示：

   Current State:
   | Agent | Skills | MCP Servers | Config Exists |
   |-------|--------|-------------|---------------|
   | Claude (source) | 5 plugins | 4 servers | yes |
   | Gemini | no link | 2 servers | yes |
   | Codex | → ~/.claude/plugins | 4 servers | yes |
   

フェーズ 2：スキルを同期（シンボリックリンク／ジャンクション）

対象が targets に含まれる場合、各対象（gemini、codex）について：

1. リンク先のパスを決定：

   • Gemini：~/.gemini/skills
   • Codex：~/.codex/skills

2. 正しくリンクされているか確認：

   • リンクが存在し、正しいソースを指している場合 → スキップ（同期済み）
   • リンクが存在するが、誤ったソースを指している場合 → 警告し、置き換える前にユーザーに確認
   • 通常のディレクトリ（リンクではない）が存在する場合 → 「同期先はリンクではなく実ディレクトリです。データ損失を避けるためスキップします」と警告

3. ソースを決定：

   • プラグインが 1 つの場合：プラグインディレクトリに直接リンク
   • 複数のプラグインがある場合：共有するプラグインをユーザーに確認

4. リンクを作成：

   OS	コマンド
   Windows	cmd /c mklink /J "{target_path}" "{source_path}"
   macOS / Linux	ln -s "{source_path}" "{target_path}"

5. 検証： リンクが存在し、正しく解決されることを確認

フェーズ 3：MCP 設定を同期

ソース： ~/.claude.json（優先）＋ ~/.claude/settings.json（フォールバック）→ 統合された mcpServers

3a: Claude → Gemini（JSON → JSON）

1. Claude の mcpServers を JSON オブジェクトとして読み取ります
2. Gemini の settings.json を読み取ります（存在しない場合は {} を作成します）
3. マージ戦略： キー名が同じ場合、Claude のサーバーで Gemini のサーバーを上書きします。Gemini のみにあるサーバーは保持します。
4. 更新した settings.json を書き込みます

変換： トランスポートタイプのマッピングが必要です。

Claude のフィールド	Gemini のフィールド	備考
type: "http" + url	httpUrl	Streamable HTTP
type: "sse" + url	url	SSE トランスポート
command + args	command + args + cwd	stdio（同じ形式）
env	env	同じ形式（Gemini では $VAR_NAME 構文）
headers	headers	同じ形式（JSON オブジェクト。url／httpUrl 用）

Gemini 固有のフィールド（Claude からはマッピングされません）：

• timeout — リクエストのタイムアウト（ミリ秒、デフォルト：10 分）
• trust — ツールの確認を省略します
• includeTools / excludeTools — ツールの許可リスト／ブロックリスト

3b: Claude → Codex（JSON → TOML）

1. Claude の mcpServers を JSON オブジェクトとして読み取ります

2. Codex の config.toml を読み取ります（存在しない場合は空のファイルを作成します）

3. 各サーバーを変換します：

   Claude の JSON フィールド	Codex の TOML フィールド	備考
   command	command	同じ
   args	args	JSON 配列 → TOML 配列
   env	[mcp_servers.{name}.env]	入れ子のテーブル
   type: "http" + url	url	Streamable HTTP（Codex は url の有無で自動判定します）
   type: "sse" + url	url	SSE → Streamable HTTP（同じ url フィールド）
   headers	http_headers	キー名が異なります！ 静的なヘッダー値

   変換例：

   "context7": {
     "command": "npx",
     "args": ["-y", "@upstash/context7-mcp"]
   }
   

   [mcp_servers.context7]
   command = "npx"
   args = ["-y", "@upstash/context7-mcp"]
   

4. マージ戦略： Claude のサーバーで上書きします。Codex のみにあるサーバーは保持します。

5. 更新した config.toml を書き込みます

Codex 固有のフィールド（そのまま保持し、Claude に対応する項目はありません）：

• bearer_token_env_var — Codex のベアラートークン認証
• enabled_tools / disabled_tools — Codex のツールフィルタリング
• startup_timeout_sec / tool_timeout_sec — Codex のタイムアウト
• enabled / required — Codex のサーバーライフサイクル
• env_vars / env_http_headers — Codex の環境変数ベースのヘッダー

Phase 4: レポート

Sync Complete:
| Action | Target | Status |
|--------|--------|--------|
| Skills symlink | Gemini | Created → ~/.claude/plugins/... |
| Skills symlink | Codex | Already linked |
| MCP sync | Gemini | 4 servers synced (2 new, 2 updated) |
| MCP sync | Codex | 4 servers synced (1 new, 3 updated) |

---

重要なルール

1. Claude を信頼できる唯一の情報源とします。 Claude の設定には書き込みません。読み取り専用のソースです。
2. 非破壊的にマージします。 対象のみにあるサーバー／設定は保持します。追加または更新するのは Claude のサーバーのみです。
3. データ損失を防ぎます。 対象が実ディレクトリ（シンボリックリンクではない）の場合は警告して処理をスキップし、決して削除しません。
4. 書き込み前にバックアップします。 設定ファイルを変更する前に、.bak コピーを作成します。
5. まずドライランを行います。 dry_run=true の場合は、実行せずに予定しているすべての操作を表示します。
6. 競合時は確認します。 シンボリックリンクが別のソースを指している場合は、ユーザーに確認し、自動で置き換えません。

避けるべきパターン

• Gemini／Codex から Claude の設定に書き込む（逆方向の同期）
• 同期中に対象のみにある MCP サーバーを削除する
• シンボリックリンクの中にシンボリックリンクを作成する（循環）
• バックアップなしで設定ファイルを変更する

---

完了の定義

• Claude の設定を正常に読み取りました
• 各対象の Skills シンボリックリンクを作成／確認しました
• MCP の設定を形式変換して同期しました（Codex の場合は JSON→TOML）
• 設定を変更する前にバックアップファイルを作成しました
• すべての操作と警告を含むレポートを表示しました

---

バージョン： 1.1.0 最終更新日： 2026-03-09