skills-sync

Skills Sync

Overview

Sync ~/.agents/commands/ and ~/.agents/skills/ to various AI tool directories via symbolic links, enabling cross-tool sharing of commands and skills.

Supported syncfiles and directories：

Commands: Sync .md command files and command directories
Skills: Sync skill directories and related files

Core principles

Symbolic links instead of copies: Use symbolic links to avoid duplicate maintenance
Smart skip: Existing valid links will not be recreated
Automatic cleanup: Remove invalid symbolic links pointing to non-existent targets
Cross-platform support: Python implementation, supports macOS/Linux/Windows

When to use

digraph when_to_use {
    "需要同步 commands/skills?" [shape=diamond];
    "同步到 Claude?" [shape=diamond];
    "同步到 CodeBuddy?" [shape=diamond];
    "同步到多个工具?" [shape=diamond];

    "使用 skills-sync" [shape=box];
    "指定 --target claude" [shape=box];
    "指定 --target codebuddy" [shape=box];
    "指定 --target claude,codebuddy" [shape=box];

    "需要同步 commands/skills?" -> "同步到 Claude?" [label="是"];
    "需要同步 commands/skills?" -> "手动操作" [label="否"];

    "同步到 Claude?" -> "使用 skills-sync" [label="是"];
    "同步到 Claude?" -> "同步到 CodeBuddy?" [label="否"];

    "同步到 CodeBuddy?" -> "使用 skills-sync" [label="是"];
    "同步到 CodeBuddy?" -> "同步到多个工具?" [label="否"];

    "同步到多个工具?" -> "使用 skills-sync" [label="是"];
    "同步到多个工具?" -> "手动操作" [label="否"];

    "使用 skills-sync" -> "指定 --target claude" [label="Claude"];
    "使用 skills-sync" -> "指定 --target codebuddy" [label="CodeBuddy"];
    "使用 skills-sync" -> "指定 --target claude,codebuddy" [label="多个工具"];
}

Use cases:

After adding a new command or skill in ~/.agents/ , you need to sync it to Claude
After updating a skill, you need to ensure all tools use the latest version
Multiple AI tools need to share the same set of commands and skills
Clean up invalid symbolic links

Not applicable to:

Needing to maintain different versions of commands for different tools
Copying files instead of creating symbolic links

Quick reference

Target	Command
Sync commands to Claude	`uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude --type commands`
Sync skills to Claude	`uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude --type skills`
Sync both to Claude	`uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude --type both`
Sync both to CodeBuddy	`uv run --directory ~/.agents/skills/skills-sync python sync.py --target codebuddy --type both`
Sync both to multiple tools	`uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude,codebuddy --type both`

Target paths

Tool	Commands path	Skills path
Claude	`~/.claude/commands/`	`~/.claude/skills/`
CodeBuddy	`~/.codebuddy/commands/`	`~/.codebuddy/skills/`

Implementation

The script is located at:~/.agents/skills/skills-sync/sync.py

Features

Supports files and directories: Sync .md command files and command/skill directories
Smart creation: Only create non-existent symbolic links
Validity check: Verify whether existing symbolic links point to existing targets
Automatic cleanup: Remove invalid symbolic links pointing to non-existent targets
Batch sync: Supports syncing to multiple tools simultaneously (comma-separated)
Selective sync: Can choose to sync only commands, skills, or both
Hidden file filtering: Automatically skip .DS_Store and other hidden files

Output symbol descriptions

✓ - Successful operation
⚠ - Skipped (target already exists and is not a symbolic link)
✗ - Error or invalid link removed

Common errors

Error	Cause	Solution
`源目录不存在`	`~/.agents/commands/` or `~/.agents/skills/` does not exist	Create the corresponding source directory
`创建失败`	Insufficient permissions or target path conflict	Check target directory permissions
`目标已存在且不是软链接`	A file/directory with the same name exists at the target location	Manually delete or rename the target
`未知的目标工具`	Typo or unsupported tool	Check the `--target` parameter

Practical applications

Typical workflow:

# 1. 在 ~/.agents/ 中创建新 skill
mkdir -p ~/.agents/skills/my-skill
echo "..." > ~/.agents/skills/my-skill/SKILL.md

# 2. 同步到 Claude
uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude --type skills

# 3. 同步到 CodeBuddy
uv run --directory ~/.agents/skills/skills-sync python sync.py --target codebuddy --type skills

# 或一次性同步到两者
uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude,codebuddy --type skills

Clean up invalid links:

# 运行同步会自动清理无效链接
uv run --directory ~/.agents/skills/skills-sync python sync.py --target claude --type both