Claude Code 环境一键同步工具

从 GitHub 仓库一键同步所有配置到本地 Claude Code 环境。

功能概述

本 skill 提供一键同步功能，将配置从 GitHub 仓库同步到本地：

• sync_env.py - 同步所有配置到本地

同步内容

GitHub 仓库结构

your-claude-env/              (GitHub 仓库)
├── env-setup.skill/          (或任意名称，放在 skills/ 下)
│   ├── SKILL.md
│   ├── scripts/
│   │   ├── sync_env.py       (主同步脚本)
│   │   ├── backup_env.py     (备份脚本，可选)
│   │   └── restore_env.py    (恢复脚本，可选)
│   └── config/               (配置模板目录)
│       ├── output-styles/    (对话风格配置)
│       │   ├── laowang-engineer.md
│       │   ├── engineer-professional.md
│       │   └── ...
│       ├── CLAUDE.md         (全局提示词)
│       └── mcp_config.json   (MCP 服务器配置)

使用方法

一、初始化 GitHub 仓库

在主设备上创建仓库：

# 1. 创建项目目录
mkdir claude-env-sync
cd claude-env-sync

# 2. 复制 env-setup skill
cp -r ~/.claude/skills/env-setup ./

# 3. 复制当前配置到 config/
cp -r ~/.claude/output-styles/* env-setup/config/output-styles/
cp ~/.claude/CLAUDE.md env-setup/config/

# 4. 提取 MCP 配置
# (手动创建或使用脚本提取)
# mcp_config.json 格式见下方

# 5. 推送到 GitHub
git init
git add .
git commit -m "Initial Claude env config"
git remote add origin https://github.com/yourusername/claude-env-sync.git
git push -u origin main

二、在新设备上同步

# 1. 克隆仓库到 skills 目录
cd ~/.claude/skills
git clone https://github.com/yourusername/claude-env-sync.git

# 2. 运行同步脚本
python ~/.claude/skills/claude-env-sync/env-setup/scripts/sync_env.py

# 3. 重启 Claude Code

三、命令行选项

# 基本用法（同步所有配置）
python scripts/sync_env.py

# 强制覆盖已存在的文件
python scripts/sync_env.py --force

# 只同步特定组件
python scripts/sync_env.py --components output_styles mcp_config

# 指定 Claude 目录
python scripts/sync_env.py --claude-dir "/path/to/.claude"

同步选项：

• output_styles - 同步对话风格配置
• claude_md - 同步全局 CLAUDE.md
• mcp_config - 同步 MCP 服务器配置

配置文件格式

mcp_config.json

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

注意： 敏感信息（API keys）建议使用环境变量或不在仓库中提交。

使用场景

场景 1：多设备环境统一

在多台电脑上保持一致的 Claude Code 配置：

# 主设备：更新配置后
git add .
git commit -m "Update config"
git push

# 其他设备：拉取并同步
git pull
python scripts/sync_env.py

场景 2：团队共享配置

团队成员共享统一的 output-styles 和 MCP 配置：

1. 创建团队 GitHub 仓库
2. 每个成员克隆到 ~/.claude/skills/
3. 定期运行 sync_env.py 同步更新

场景 3：快速换电脑

# 新电脑上
git clone https://github.com/yourusername/claude-env-sync.git ~/.claude/skills/
python ~/.claude/skills/claude-env-sync/env-setup/scripts/sync_env.py --force

场景 4：版本管理配置

# 回滚到之前的配置
git log --oneline
git checkout <commit-hash>
python scripts/sync_env.py --force

工作流程

日常更新流程

1. 修改本地配置
   ↓
2. 更新 config/ 目录
   ↓
3. git add . && git commit -m "Update xxx"
   ↓
4. git push
   ↓
5. 其他设备: git pull && python scripts/sync_env.py

注意事项

MCP 配置同步

• MCP 配置采用合并模式，不会覆盖现有的其他 MCP 服务器
• 同一个服务器的配置会被更新
• 敏感信息（API tokens）建议：
  • 使用环境变量
  • 或在 mcp_config.json 中使用占位符，本地手动填充

文件覆盖行为

• 不使用 --force：跳过已存在的文件（除了 MCP 配置，始终合并）
• 使用 --force：覆盖已存在的文件

重启 Claude Code

同步完成后需要重启 Claude Code 才能生效：

• Output styles 会重新加载
• MCP 服务器会重新连接
• CLAUDE.md 会更新

跨平台兼容

• 脚本自动处理 Windows/macOS/Linux 路径差异
• 配置文件使用 UTF-8 编码

故障排查

同步失败

问题： "config/output-styles not found"

• 解决： 确认仓库结构正确，config/ 目录存在

问题： ".claude.json not found"

• 解决： 确认 Claude Code 已安装并运行过一次

问题： MCP 配置没有生效

• 解决： 检查 mcp_config.json 格式是否正确，重启 Claude Code

Git 相关

问题： 推送失败

• 解决： 检查 GitHub 仓库权限、网络连接

高级用法

分支管理

# 创建设备特定配置分支
git checkout -b my-custom-config

# 切换回主配置
git checkout main

部分同步

# 只同步风格，保留其他配置
python scripts/sync_env.py --components output_styles

# 只同步 MCP，不改变风格
python scripts/sync_env.py --components mcp_config

自动化同步（可选）

创建定期同步脚本：

# sync.sh
#!/bin/bash
cd ~/.claude/skills/claude-env-sync
git pull
python env-setup/scripts/sync_env.py

添加到 cron 或 Task Scheduler 定期执行。