sync-skills

Sync Skills

Sync skills from a local directory, GitHub repository, or skillsmp.com page to multiple AI coding tool directories.

🚨 Core requirements：

1. Must include ~/.agents/skills as a sync target (auto-create if it does not exist)
2. Must use AskUserQuestion to let the user select target directories
3. Show the sync plan and wait for the user's final confirmation
4. Skills with the same name are overwritten directly, without a separate prompt

When to Use

Trigger scenarios:

• The user provides a local skill folder path
• The user provides a GitHub repository URL
• The user provides a skillsmp.com skill page URL
• Need to distribute skills to multiple AI tool directories

Workflow:

用户输入 → 识别来源类型 → 收集目标目录 → 用户选择目标 → 展示计划 → 用户确认 → 执行同步 → 报告结果

Workflow

Step 1: Identify the source type

# 判断输入类型
if [[ "$input" =~ ^(/|~/|\./) ]]; then
    SOURCE_TYPE="local"
    SOURCE_PATH="$input"
elif [[ "$input" =~ github\.com ]]; then
    SOURCE_TYPE="github"
    SOURCE_URL="${input%.git}"
elif [[ "$input" =~ skillsmp\.com ]]; then
    SOURCE_TYPE="skillsmp"
    SOURCE_URL="$input"
else
    echo "❌ 无法识别来源类型"
    exit 1
fi

Step 2: Collect target directories

# 定义所有可能的目标目录
ALL_TARGETS=(
    "$HOME/.agents/skills"      # MANDATORY
    "$HOME/.claude/skills"
    "$HOME/.qoder/skills"
    "$HOME/.copilot/skills"
    "$HOME/.cursor/skills"
    "$HOME/.gemini/skills"
    "$HOME/.codex/skills"
    "$HOME/.config/opencode/skill"
    "$HOME/.codeium/windsurf/skills"
    "$HOME/.qwen/skills"
    "$HOME/.openclaw/skills"
)

# 确保 ~/.agents/skills 存在
mkdir -p "$HOME/.agents/skills"

# 收集已存在的目录
EXISTING_TARGETS=("$HOME/.agents/skills")
for target in "${ALL_TARGETS[@]:1}"; do
    [ -d "$target" ] && EXISTING_TARGETS+=("$target")
done

Step 3: Use AskUserQuestion to let the user select targets

<parameter name="questions">[
  {
    "question": "选择要同步到的目标目录（可多选）",
    "header": "目标目录",
    "multiSelect": true,
    "options": [
      {
        "label": "~/.agents/skills",
        "description": "通用技能目录（所有工具共用）",
        "markdown": "✅ **必选**"
      },
      {
        "label": "~/.claude/skills",
        "description": "Claude Code 技能目录"
      },
      {
        "label": "~/.qoder/skills",
        "description": "Qoder 技能目录"
      }
      // ... 根据实际存在的目录动态生成
    ]
  }
]</parameter>

Key points:

• ~/.agents/skills Always as the first option and marked as required
• Support multiple selection
• Users can enter custom paths via "Other"

Step 4: Prepare the skill content

case "$SOURCE_TYPE" in
    local)
        SKILL_NAME=$(basename "$SOURCE_PATH")
        SKILL_SOURCE="$SOURCE_PATH"
        ;;
    github)
        TEMP_DIR=$(mktemp -d)
        git clone -q "$SOURCE_URL" "$TEMP_DIR"
        # 查找 SKILL.md 位置
        if [ -f "$TEMP_DIR/SKILL.md" ]; then
            SKILL_NAME=$(basename "$SOURCE_URL")
            SKILL_SOURCE="$TEMP_DIR"
        elif find "$TEMP_DIR" -name "SKILL.md" -quit; then
            SKILL_SOURCE=$(find "$TEMP_DIR" -name "SKILL.md" -printf "%h" -quit)
            SKILL_NAME=$(basename "$SKILL_SOURCE")
        fi
        ;;
    skillsmp)
        # 抓取并解析页面内容
        TEMP_DIR=$(mktemp -d)
        # ... 解析逻辑 ...
        ;;
esac

Step 5: Show the sync plan and wait for confirmation

Show the sync plan to the user in a clear format:

📋 同步计划：

来源：$SOURCE_TYPE
Skill：$SKILL_NAME

目标目录（共 $SELECTED_COUNT 个）：
  1. ~/.agents/skills [新建]
  2. ~/.claude/skills [覆盖已有]
  3. ~/custom/skills [新建]

⚠️  同名 skill 将被直接覆盖，不会备份

确认执行？(Y/n)

Step 6: Execute the sync

for target in "${SELECTED_TARGETS[@]}"; do
    # 创建目标目录（如不存在）
    mkdir -p "$target"

    # 删除同名 skill
    if [ -d "$target/$SKILL_NAME" ]; then
        echo "  → 覆盖: $target/$SKILL_NAME"
        rm -rf "$target/$SKILL_NAME"
    else
        echo "  → 新建: $target/$SKILL_NAME"
    fi

    # 复制 skill
    cp -r "$SKILL_SOURCE" "$target/"
done

# 清理临时目录
[ -n "$TEMP_DIR" ] && rm -rf "$TEMP_DIR"

Step 7: Report the results

✅ 同步完成！

已成功同步到 $SUCCESS_COUNT 个目录：
  ✓ ~/.agents/skills
  ✓ ~/.claude/skills
  ✓ ~/custom/skills

❌ 失败 $FAIL_COUNT 个目录：
  ✗ ~/.qoder/skills (权限拒绝)

Reference

Supported target directories

Tool	User Level
Agents (Universal) ⭐	~/.agents/skills [Required]
Claude Code	~/.claude/skills
GitHub Copilot	~/.copilot/skills
Cursor	~/.cursor/skills
Qoder	~/.qoder/skills
Gemini CLI	~/.gemini/skills
OpenAI Codex	~/.codex/skills
Windsurf	~/.codeium/windsurf/skills
Qwen Code	~/.qwen/skills
OpenClaw	~/.openclaw/skills
OpenCode	~/.config/opencode/skill

Source type identification

# 本地目录
/path/to/skill
./skill
~/skill

# GitHub URL
https://github.com/user/repo
https://github.com/user/repo.git
git@github.com:user/repo.git

# skillsmp.com URL
https://skillsmp.com/skills/skill-name

Complete AskUserQuestion example

<function_calls>
<invoke name="AskUserQuestion">
<parameter name="questions">[
  {
    "question": "选择要同步到的目标目录（可多选，或选择「其他」输入自定义路径）：",
    "header": "目标目录选择",
    "multiSelect": true,
    "options": [
      {
        "label": "~/.agents/skills",
        "description": "通用技能目录（所有工具共用）",
        "markdown": "✅ **必选** - 多个 AI 工具共享"
      },
      {
        "label": "~/.claude/skills",
        "description": "Claude Code 技能目录"
      },
      {
        "label": "~/.qoder/skills",
        "description": "Qoder 技能目录"
      }
    ]
  },
  {
    "question": "同名 skill 将被直接覆盖，是否继续？",
    "header": "覆盖策略确认",
    "multiSelect": false,
    "options": [
      {"label": "继续执行", "description": "直接覆盖同名 skill"},
      {"label": "取消操作", "description": "取消本次同步"}
    ]
  }
]</parameter>
</invoke>
</function_calls>

Gotchas

Incorrect	Correct approach
Skip ~/.agents/skills	Always include, create if it does not exist
Do not use AskUserQuestion	Must useto let the user select targets
Do not show the sync plan	Must showand wait for user confirmation
Sync to a non-existent directory	Check first -d, create if it does not exist
Incorrect judgment of GitHub repository structure	Locate SKILL.md first
Forget to clean up temporary files	Always rm -rf /tmp/skill-sync-*
GitHub URL has a .git suffix	First use ${url%.git} to remove it
Do not handle user custom paths	Support via the "Other" option

🚨 Most common mistakes：

1. Skip ~/.agents/skills - This is a serious mistake
2. Execute directly without showing the sync plan - Poor user experience