Skills Sync
通过符号链接在多个 AI 编码工具之间同步 skills — 只维护一份，到处可见。
脚本通过创建和维护符号链接来工作，永远不会覆盖真实文件。如果一个位置已经有真实文件（非符号链接），脚本会跳过它。
第一步：永远先检查配置
在做任何事之前，运行：
bash "$(script_path)" config --show
如果配置缺失，运行 config（不带参数），让用户交互式选择工具。不要自动配置默认工具列表 — 这一步停下来让用户自己选。
核心决策
用户说的话 → 你该做的事：
| 用户意图 | 命令 |
|---|---|
| "同步 skills" / "sync" 语义 | sync --tool <当前工具> |
| "拉取" / "pull" | pull --to <当前工具> |
| "推送" / "push" | push --from <当前工具> |
| 删除链接但保留文件 | unlink --from <指定工具> |
| 查看当前状态 | status |
| 查看详细清单 | list |
| 问版本 | version |
| 首次使用 / 没配置过 | config（交互式） |
什么是"当前工具"
你在哪个 AI 工具里运行，那个就是当前工具。映射规则：
| 运行时 | 规范名 |
|---|---|
| Claude Code | claude |
| Codex | codex |
| Qoder | qoder |
如果用户明确指定了不同的工具，以用户说的为准。
脚本路径公式
~/.<规范工具名>/skills/skills-sync/scripts/sync-skills.sh
例如：当前工具是 claude → 脚本路径是 ~/.claude/skills/skills-sync/scripts/sync-skills.sh。
后面所有命令示例用 SYNC 代替完整路径，实际执行时替换为上面算出的路径。
命令参考
config — 配置工具列表
bash SYNC config # 交互式选择
bash SYNC config --set claude,codex # 直接指定
bash SYNC config --show # 查看当前配置
bash SYNC config --add codebuddy # 添加一个工具
bash SYNC config --remove codebuddy # 移除一个工具
配置文件位置：~/.agents/sync-skills.json
sync — 双向同步（推荐）
一条命令完成 pull + push：先把其他工具的 skills 拉到 center 工具，再把 center 工具的 skills 推到其他工具。
bash SYNC sync --tool claude # claude 作为中心，双向同步
bash SYNC sync --tool claude --scope global # 只同步 global 作用域
bash SYNC sync --tool claude --skill find-skills # 只同步一个 skill
bash SYNC sync --tool claude --dry-run # 只预览，不执行
pull — 把其他工具的 skills 拉过来
bash SYNC pull --to claude # 从所有工具拉到 claude
bash SYNC pull --to claude --from agents --scope global # 仅从 agents 拉取
bash SYNC pull --to claude --skill find-skills # 只拉一个 skill
bash SYNC pull --to claude --dry-run # 只预览，不执行
push — 把当前工具的 skills 推到其他工具
bash SYNC push --from claude # 推到所有其他工具
bash SYNC push --from claude --to codex # 只推到 codex
bash SYNC push --from claude --skill ddd-java # 只推一个 skill
unlink — 删除符号链接（保留真实文件）
bash SYNC unlink --from claude --to codex,qoder --scope global
status / list / version — 只读查看
bash SYNC status
bash SYNC list
bash SYNC version
通用参数
| 参数 | 说明 | 默认值 |
|---|---|---|
--tool <tool> |
sync 的中心工具（双向同步） | 必填 |
--from <tool\|all> |
pull 的来源 | all（含 agents） |
--to <tool\|all> |
push/unlink 的目标 | all（不含 agents） |
--scope global\|project\|both |
同步范围 | both |
--skill <name> |
只操作某个 skill | 全部 |
--dry-run |
只预览变更 | — |
--project-dir <path> |
指定项目根目录 | 自动检测 git root |
支持的工具
| Tool | Global | Project |
|---|---|---|
| agents | ~/.agents/skills/ |
— (只读来源) |
| claude | ~/.claude/skills/ |
.claude/skills/ |
| codex | ~/.codex/skills/ |
.codex/skills/ |
| qoder | ~/.qoder/skills/ |
.qoder/skills/ |
| cline | ~/.cline/skills/ |
.cline/skills/ |
| codebuddy | ~/.codebuddy/skills/ |
.codebuddy/skills/ |
| cursor | ~/.cursor/skills/ |
.cursor/skills/ |
| gemini | ~/.gemini/skills/ |
.gemini/skills/ |
| github | ~/.github/skills/ |
.github/skills/ |
| lingma | ~/.lingma/skills/ |
.lingma/skills/ |
| opencode | ~/.opencode/skills/ |
.opencode/skills/ |
| qwen | ~/.qwen/skills/ |
.qwen/skills/ |
| trae | ~/.trae/skills/ |
.trae/skills/ |
agents 是共享只读来源 — 可以 pull，不能作为 push、unlink 的目标。
脚本只操作 sync-skills.json 中已配置的工具。
执行流程
- 检查配置 → 缺失则走
config交互式，到这步停下 - 确定用户意图（同步/拉取/推送/查看/删除）
- 修改类命令先跑
--dry-run，除非用户明确说直接执行 - dry-run 结果符合预期后再执行真实命令
- 汇报结果
汇报格式
Goal: bidirectional sync with claude as center
Command: bash ~/.claude/skills/skills-sync/scripts/sync-skills.sh sync --tool claude --scope global
Scope: global
Result: 2 pulled, 3 pushed, 1 updated, 5 already correct
Notes: no real files were overwritten
边界情况
- 目标已有正确符号链接 → 跳过（无需操作）
- 目标符号链接指向错误 → 更新为正确来源
- 目标是真实文件 → 跳过（永远不覆盖真实文件）
agents只能作为来源，不能作为目标project作用域仅适用于支持项目级目录的工具- 项目根目录自动用
git rev-parse --show-toplevel检测，失败则回退到当前目录
用户表达不明确时
只在选择会实质性改变行为时才追问：
- 哪个工具作为来源？
- global / project / both？
- dry-run 还是直接执行？
如果用户说得模糊且风险低，按默认值走：scope=both，先 dry-run，再确认执行。
