ln-004-agent-sync

パス： ファイルパス（shared/、references/、../ln-*）はスキルリポジトリのルートからの相対パスです。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\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/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) | 2 plugins | 4 servers | yes |
   | Gemini | no link | 2 servers | yes |
   | Codex | → ~/.claude/plugins | 4 servers | yes |
   

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

各 target が 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/settings.json → mcpServers ブロック

3a：Claude → Gemini（JSON → JSON）

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

変換： 不要です。同一の形式です。

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	HTTP トランスポート
   type: "sse" + url	url	SSE トランスポート

   変換例：

   "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 ではそのまま保持）：

• bearer_token_env_var — Claude に相当する項目がありません
• enabled_tools / disabled_tools — Claude に相当する項目がありません

フェーズ 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 サーバーを削除する
• シンボリックリンクの中にシンボリックリンクを作成する（循環）
• バックアップを作成せずに設定ファイルを変更する

---

完了の定義

#	基準
1	Claude の設定を正常に読み取れている
2	各ターゲットにスキルのシンボリックリンクを作成・確認している
3	形式変換（Codex の場合は JSON→TOML）を行って MCP の設定を同期している
4	設定を変更する前にバックアップファイルを作成している
5	すべての操作と警告を含むレポートを表示している

---

バージョン： 1.0.0 最終更新日： 2026-02-15