ln-004-agent-sync

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Agent Sync (Standalone Utility)

Type: Standalone Utility Category: 0XX Shared

Synchronizes skills and MCP server configurations from Claude Code (source of truth) to Gemini CLI and Codex CLI. Creates symlinks for skills, copies/converts MCP settings.

---

When to Use This Skill

• After adding/removing MCP servers in Claude Code settings
• After installing new plugins in Claude Code
• First-time setup of Gemini CLI or Codex CLI alongside Claude Code
• Periodic sync to keep all agents aligned

---

Input Parameters

Parameter	Required	Default	Description
targets	No	both	gemini, codex, or both
mode	No	full	skills (symlinks only), mcp (MCP only), or full (both)
dry_run	No	false	Show planned actions without executing

---

Workflow

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

Phase 0: OS Detection

Check	Result	Impact
uname or platform	win32 / darwin / linux	Junction vs symlink
Home directory	$HOME or $USERPROFILE	Config paths

Paths by OS:

Agent	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

Phase 1: Discover Current State

1. Read Claude settings:

   • Parse ~/.claude/settings.json → extract mcpServers block
   • If no mcpServers → WARN "No MCP servers configured in Claude", skip MCP sync

2. Read target configs (if exist):

   • Gemini: Parse ~/.gemini/settings.json → extract existing mcpServers
   • Codex: Parse ~/.codex/config.toml → extract existing [mcp_servers.*]

3. Detect installed plugins:

   • Glob ~/.claude/plugins/*/plugin.json → list plugin directories
   • Also check if skills repo itself is a plugin source

4. Check existing symlinks:

   • ~/.gemini/skills → exists? points where?
   • ~/.codex/skills → exists? points where?

5. Show current state:

   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 |
   

Phase 2: Sync Skills (symlinks/junctions)

FOR EACH target IN (gemini, codex) WHERE target in targets:

1. Determine link path:

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

2. Check if already linked correctly:

   • IF link exists AND points to correct source → SKIP (already synced)
   • IF link exists AND points to wrong source → WARN, ask user before replacing
   • IF regular directory (not link) exists → WARN "Target is a real directory, not a link. Skip to avoid data loss."

3. Determine source:

   • IF single plugin: link directly to plugin dir
   • IF multiple plugins: ask user which plugin to share

4. Create link:

   OS	Command
   Windows	cmd /c mklink /J "{target_path}" "{source_path}"
   macOS / Linux	ln -s "{source_path}" "{target_path}"

5. Verify: Check link exists and resolves correctly

Phase 3: Sync MCP Settings

Source: ~/.claude/settings.json → mcpServers block

3a: Claude → Gemini (JSON → JSON)

1. Read Claude mcpServers as JSON object
2. Read Gemini settings.json (or create {} if missing)
3. Merge strategy: Claude servers override Gemini servers by key name. Gemini-only servers preserved.
4. Write updated settings.json

Conversion: None needed — identical format.

3b: Claude → Codex (JSON → TOML)

1. Read Claude mcpServers as JSON object

2. Read Codex config.toml (or create empty if missing)

3. Convert each server:

   Claude JSON field	Codex TOML field	Notes
   command	command	Same
   args	args	JSON array → TOML array
   env	[mcp_servers.{name}.env]	Nested table
   type: "http" + url	url	HTTP transport
   type: "sse" + url	url	SSE transport

   Example conversion:

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

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

4. Merge strategy: Claude servers override. Codex-only servers preserved.

5. Write updated config.toml

Unsupported conversions (preserve as-is in Codex):

• bearer_token_env_var — no Claude equivalent
• enabled_tools / disabled_tools — no Claude equivalent

Phase 4: Report

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) |

---

Critical Rules

1. Claude = source of truth. Never write TO Claude settings. Read-only source.
2. Non-destructive merge. Target-only servers/settings preserved. Only Claude servers added/updated.
3. No data loss. If target is a real directory (not symlink) — warn and skip, never delete.
4. Backup before write. Before modifying any config file, create .bak copy.
5. Dry run first. If dry_run=true, show all planned actions without executing.
6. Ask on conflict. If symlink points to different source — ask user, don't auto-replace.

Anti-Patterns

• Writing TO Claude settings from Gemini/Codex (reverse sync)
• Deleting target-only MCP servers during sync
• Creating symlinks inside symlinks (circular)
• Modifying config files without backup

---

Definition of Done

#	Criterion
1	Claude settings read successfully
2	Skills symlinks created/verified for each target
3	MCP settings synced with format conversion (JSON→TOML for Codex)
4	Backup files created before any config modification
5	Report shown with all actions and warnings

---

Version: 1.0.0 Last Updated: 2026-02-15