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

Read Claude settings:

• Parse ~/.claude/settings.json → extract mcpServers block

• If no mcpServers → WARN "No MCP servers configured in Claude", skip MCP sync

Read target configs (if exist):

• Gemini: Parse ~/.gemini/settings.json → extract existing mcpServers

• Codex: Parse ~/.codex/config.toml → extract existing [mcp_servers.*]

Detect installed plugins:

• Glob ~/.claude/plugins/*/plugin.json → list plugin directories

• Also check if skills repo itself is a plugin source

Check existing symlinks:

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

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

Show current state:

Current State:

Phase 2: Sync Skills (symlinks/junctions)

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

Determine link path:

• Gemini: ~/.gemini/skills

• Codex: ~/.codex/skills

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

Determine source:

• IF single plugin: link directly to plugin dir

• IF multiple plugins: ask user which plugin to share

Create link:

OS Command

Windows cmd /c mklink /J "{target_path}" "{source_path}"

macOS / Linux ln -s "{source_path}" "{target_path}"

Verify: Check link exists and resolves correctly

Phase 3: Sync MCP Settings

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

3a: Claude → Gemini (JSON → JSON)

• Read Claude mcpServers as JSON object

• Read Gemini settings.json (or create {} if missing)

• Merge strategy: Claude servers override Gemini servers by key name. Gemini-only servers preserved.

• Write updated settings.json

Conversion: None needed — identical format.

3b: Claude → Codex (JSON → TOML)

Read Claude mcpServers as JSON object

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

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

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

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:

Critical Rules

• Claude = source of truth. Never write TO Claude settings. Read-only source.

• Non-destructive merge. Target-only servers/settings preserved. Only Claude servers added/updated.

• No data loss. If target is a real directory (not symlink) — warn and skip, never delete.

• Backup before write. Before modifying any config file, create .bak copy.

• Dry run first. If dry_run=true , show all planned actions without executing.

• 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