ln-004-agent-sync

路径： 文件路径（shared/、references/、../ln-*）均相对于 skills 仓库根目录。如果在当前工作目录中找不到，请定位此 SKILL.md 所在目录，并向上一级找到仓库根目录。

Agent Sync（独立工具）

类型： 独立工具
类别： 0XX Shared

将技能和 MCP 服务配置从 Claude Code（事实来源）同步到 Gemini CLI 和 Codex CLI。为技能创建符号链接，并复制/转换 MCP 设置。

---

何时使用此技能

• 在 Claude Code 设置中添加/移除 MCP 服务后
• 在 Claude Code 中安装新插件后
• 首次在 Claude Code 旁设置 Gemini CLI 或 Codex CLI 时
• 定期同步以确保所有 Agent 保持一致

---

输入参数

参数	必填	默认值	描述
targets	否	both	gemini、codex 或 both
mode	否	full	skills（仅符号链接）、mcp（仅 MCP）或 full（两者）
dry_run	否	false	显示计划执行的操作，但不实际执行

---

工作流

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

阶段 0：操作系统检测

检查项	结果	影响
uname 或平台	win32 / darwin / linux	Junction 还是符号链接
主目录	$HOME 或 $USERPROFILE	配置路径

各操作系统的路径：

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

阶段 1：发现当前状态

1. 读取 Claude 设置：

   • 解析 ~/.claude/settings.json → 提取 mcpServers 块
   • 如果没有 mcpServers → 警告“No MCP servers configured in Claude”，跳过 MCP 同步

2. 读取目标配置（如果存在）：

   • Gemini：解析 ~/.gemini/settings.json → 提取现有 mcpServers
   • Codex：解析 ~/.codex/config.toml → 提取现有 [mcp_servers.*]

3. 检测已安装的插件：

   • Glob ~/.claude/plugins/*/plugin.json → 列出插件目录
   • 同时检查 skills 仓库本身是否为插件来源

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：同步技能（符号链接/Junction）

对 targets 中的每个目标（gemini、codex）执行：

1. 确定链接路径：

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

2. 检查链接是否正确：

   • 如果链接存在且指向正确的来源 → 跳过（已同步）
   • 如果链接存在但指向错误的来源 → 警告，并在替换前询问用户
   • 如果存在普通目录（不是链接）→ 警告“目标是实际目录，不是链接。为避免数据丢失，跳过。”

3. 确定来源：

   • 如果只有一个插件：直接链接到插件目录
   • 如果有多个插件：询问用户要共享哪个插件

4. 创建链接：

   操作系统	命令
   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	为每个目标创建/验证 Skills 符号链接
3	同步 MCP 设置并转换格式（Codex 使用 JSON→TOML）
4	修改任何配置前创建备份文件
5	显示包含所有操作和警告的报告

---

版本： 1.0.0 最后更新： 2026-02-15