Sync Skills

Overview

Automatically sync skills from multiple sources to all installed AI coding tool directories. Lists all existing target directories for user confirmation before syncing.

🚨 CRITICAL REQUIREMENT: All sync operations MUST include ~/.agents/skills as the primary target. This universal skill directory is used by multiple AI coding tools and is non-negotiable. If the directory doesn't exist, it will be created automatically.

When to Use

digraph when_sync {
    "Need to sync skill?" [shape=diamond];
    "Source type?" [shape=diamond];
    "Local folder" [shape=box];
    "GitHub URL" [shape=box];
    "skillsmp.com URL" [shape=box];

    "Need to sync skill?" -> "Source type?";
    "Source type?" -> "Local folder" [label="Local path"];
    "Source type?" -> "GitHub URL" [label="github.com"];
    "Source type?" -> "skillsmp.com URL" [label="skillsmp.com"];
}

Use when:

• User provides local skill folder path
• User provides GitHub repository URL
• User provides skillsmp.com skill detail page URL
• Need to distribute skill across multiple AI tools

How it works:

1. Auto-detect source type from input
2. Prepare skill content based on source
3. Check all target directories (only existing ones)
4. List existing targets for user confirmation
5. Copy/clone to each confirmed target

Target Directories

Checks these paths in order, only syncs if directory exists:

⚠️ CRITICAL: ~/.agents/skills is a MANDATORY sync target. This universal skill directory is used by multiple AI coding tools and MUST ALWAYS be included in sync operations. Never skip this directory.

Quick Reference

Basic Usage:

./sync-skill.sh <source>

Examples:

# Local folder
./sync-skill.sh /Users/user/skills/my-skill

# GitHub repository
./sync-skill.sh https://github.com/user/skill-repo

# skillsmp.com page
./sync-skill.sh https://skillsmp.com/skills/skill-name

Source Type Detection

# Local folder
/Users/user/skills/my-skill
./skills/my-skill
~/skills/my-skill

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

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

Sync Commands by Source Type

Local folder:

# MANDATORY: Always sync to ~/.agents/skills first
cp -r /path/to/skill-name ~/.agents/skills/
cp -r /path/to/skill-name ~/.claude/skills/
cp -r /path/to/skill-name ~/.qoder/skills/
# ... for each existing target

GitHub:

# Clone to temp
git clone https://github.com/user/skill-repo.git /tmp/skill-sync

# Copy skill folder (might be in subdirectory)
# MANDATORY: Always sync to ~/.agents/skills first
cp -r /tmp/skill-sync/skill-name ~/.agents/skills/
cp -r /tmp/skill-sync/skill-name ~/.claude/skills/
# ... for each existing target

# Cleanup
rm -rf /tmp/skill-sync

skillsmp.com:

# Fetch page content
curl -s https://skillsmp.com/skills/skill-name > /tmp/skill-page.html

# Parse and download skill files
# Extract skill content from page
# Create skill directory structure
# Copy to each target

Implementation

Executable script: See sync-skill.sh in this skill directory.

Features:

• Auto-detects source type (local, GitHub, skillsmp.com)
• Checks all target directories for existence
• Lists existing targets and waits for user confirmation before syncing
• Only syncs to user-confirmed directories
• Overwrites existing skills without prompting
• Cleans up temporary files after use
• Provides clear output with emoji indicators

Exit codes:

• 0: Success
• 1: Error (missing source, clone failure, etc.)

Using from AI assistant: When user asks to sync a skill, invoke the script with appropriate source:

# User says: "Sync the skill at /path/to/my-skill"
./sync-skill.sh /path/to/my-skill

# User says: "Sync this GitHub repo: https://github.com/user/skill"
./sync-skill.sh https://github.com/user/skill

Source Detection

function detectSource(input) {
  // Local folder
  if (input.startsWith('/') || input.startsWith('./') || input.startsWith('~')) {
    return { type: 'local', path: input };
  }

  // GitHub URL
  if (input.includes('github.com')) {
    const url = input.replace(/\.git$/, '');
    return { type: 'github', url };
  }

  // skillsmp.com URL
  if (input.includes('skillsmp.com')) {
    return { type: 'skillsmp', url: input };
  }

  throw new Error(`Unknown source type: ${input}`);
}

Directory Existence Check and Confirmation

# Check if directory exists and collect for confirmation
check_and_sync() {
  local source=$1
  local skill_name=$2

  # Array of all target directories
  # IMPORTANT: ~/.agents/skills is MANDATORY and must be first
  local targets=(
    "$HOME/.agents/skills"     # MANDATORY - Universal skill directory
    "$HOME/.claude/skills"
    "$HOME/.qoder/skills"
    "$HOME/.copilot/skills"
    # ... all others
  )

  local existing_targets=()

  # First pass: collect existing directories
  # MANDATORY: ~/.agents/skills must exist for sync to proceed
  local agents_dir="$HOME/.agents/skills"
  if [ ! -d "$agents_dir" ]; then
    echo "⚠️  Creating mandatory directory: $agents_dir"
    mkdir -p "$agents_dir"
  fi
  existing_targets+=("$agents_dir")

  # Collect other existing directories
  for target in "${targets[@]:1}"; do
    if [ -d "$target" ]; then
      existing_targets+=("$target")
    fi
  done

  # List existing targets and ask for confirmation
  if [ ${#existing_targets[@]} -eq 0 ]; then
    echo "❌ No target directories found. Please install at least one AI coding tool."
    exit 1
  fi

  echo "📋 Found ${#existing_targets[@]} existing target directory(s):"
  echo ""
  for i in "${!existing_targets[@]}"; do
    echo "  $((i+1)). ${existing_targets[$i]}"
  done
  echo ""
  read -p "✅ Sync to these directories? (y/N): " confirm

  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
    echo "❌ Sync cancelled by user."
    exit 1
  fi

  echo ""
  echo "🚀 Starting sync..."

  # Second pass: sync to confirmed targets
  for target in "${existing_targets[@]}"; do
    echo "  → Syncing to $target..."
    # Perform sync
  done
}

GitHub Repository Handling

# Clone to temp directory
git clone https://github.com/user/repo.git /tmp/skill-sync-XXXXX

# Find skill folder (might be root or subdirectory)
if [ -f /tmp/skill-sync-XXXXX/SKILL.md ]; then
  skill_folder="/tmp/skill-sync-XXXXX"
elif [ -d /tmp/skill-sync-XXXXx/skills/* ]; then
  skill_folder="/tmp/skill-sync-XXXXx/skills/*"
fi

# Copy to each existing target
for target in "${existing_targets[@]}"; do
  cp -r "$skill_folder" "$target/"
done

# Cleanup
rm -rf /tmp/skill-sync-XXXXX

skillsmp.com Page Handling

# Fetch page
url="https://skillsmp.com/skills/skill-name"
curl -s "$url" > /tmp/skill-page.html

# Extract skill name and files
skill_name=$(grep -o '<h1[^>]*>.*</h1>' /tmp/skill-page.html | sed 's/<[^>]*>//g')

# Download or extract skill content
# This depends on skillsmp.com's structure
# Might need to parse JSON, download files, etc.

# Create skill directory
mkdir -p "/tmp/$skill_name"

# Save content to SKILL.md
# ... parsing logic ...

# Sync to targets
for target in "${existing_targets[@]}"; do
  cp -r "/tmp/$skill_name" "$target/"
done

Common Mistakes

🚨 CRITICAL: The most serious mistake is skipping ~/.agents/skills. This directory is used by multiple AI coding tools and must always be included in every sync operation.

Conflict Handling

Policy: Always overwrite existing skills

If a skill with the same name exists in a target directory:

• Overwrite without prompting
• Log what was overwritten: "Overwriting existing skill at $target/$skill_name"
• No backup (user should use git if they need history)

Rationale: Sync operations are expected to update content. If user wants to preserve local changes, they should manage version control separately.