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.

• 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

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) | 5 plugins | 4 servers | yes |
   | Gemini | no link | 2 servers | yes |
   | Codex | → ~/.claude/plugins | 4 servers | yes |

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

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

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:
   json

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

   toml

   [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

• bearer_token_env_var

  — no Claude equivalent

• enabled_tools

  /

  disabled_tools

  — no Claude equivalent

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.

• 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