@vikasagarwal101/skill-sync 1.0.0

package/bin/skill-sync.sh

@@ -0,0 +1,1250 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# skill-sync (bundled by scripts/bundle.sh)
+# Source: https://github.com/vikasagarwal101/skill-sync
+
+# -- Configuration --
+
+CONFIG_DIR="${SKILLSYNC_CONFIG_DIR:-$HOME/.config/skill-sync}"
+MANIFEST="$CONFIG_DIR/manifest"
+CONFIG_FILE="$CONFIG_DIR/config"
+
+# Defaults (overridden by config file if present)
+declare -A SOURCES=(
+    [agents]="${SKILLSYNC_AGENTS_DIR:-$HOME/.agents/skills}"
+    [opencode]="${SKILLSYNC_OPENCODE_DIR:-$HOME/.config/opencode/skills}"
+    [codex]="${SKILLSYNC_CODEX_DIR:-$HOME/.codex/skills}"
+)
+
+declare -A TARGETS=(
+    [claude]="${SKILLSYNC_CLAUDE_DIR:-$HOME/.claude/skills}"
+)
+
+SOURCE_PRIORITY=("agents" "opencode" "codex")
+
+# Load config file if it exists (overrides defaults)
+[ -f "$CONFIG_FILE" ] && source "$CONFIG_FILE"
+
+# Global flags
+DRY_RUN=0
+
+# -- Helpers --
+
+# Safe operations that respect --dry-run
+_safe_cp() { [ $DRY_RUN -eq 1 ] && echo "  [dry-run] cp -r $1 $2" || cp -r "$1" "$2"; }
+_safe_rm() { [ $DRY_RUN -eq 1 ] && echo "  [dry-run] rm -rf $1" || rm -rf "$1"; }
+_safe_mv() { [ $DRY_RUN -eq 1 ] && echo "  [dry-run] mv $1 $2" || mv "$1" "$2"; }
+
+md5_content() {
+    find "$1" -type f -exec md5sum {} \; 2>/dev/null | awk '{print $1}' | sort | md5sum | cut -d' ' -f1
+}
+
+dir_exists() { [ -d "$1" ]; }
+
+source_for_skill() {
+    local name="$1"
+    for label in "${SOURCE_PRIORITY[@]}"; do
+        local dir="${SOURCES[$label]}"
+        if [ -f "$dir/$name/SKILL.md" ] || [ -d "$dir/$name" ]; then
+            echo "$label"
+            return 0
+        fi
+    done
+    return 1
+}
+
+source_path_for_skill() {
+    local name="$1"
+    for label in "${SOURCE_PRIORITY[@]}"; do
+        local dir="${SOURCES[$label]}"
+        if [ -f "$dir/$name/SKILL.md" ] || [ -d "$dir/$name" ]; then
+            echo "$dir/$name"
+            return 0
+        fi
+    done
+    return 1
+}
+
+all_skill_names() {
+    declare -A seen
+    for label in "${SOURCE_PRIORITY[@]}"; do
+        local dir="${SOURCES[$label]}"
+        dir_exists "$dir" || continue
+        for d in "$dir"/*/; do
+            [ -d "$d" ] || continue
+            local n
+            n=$(basename "$d")
+            [ "$n" = ".system" ] && continue
+            if [ -f "$d/SKILL.md" ]; then
+                [ -n "${seen[$n]:-}" ] && continue
+                seen[$n]=1
+                echo "$n"
+            else
+                for sub in "$d"*/; do
+                    [ -d "$sub" ] || continue
+                    [ -f "$sub/SKILL.md" ] || continue
+                    local sn nested
+                    sn=$(basename "$sub")
+                    nested="$n/$sn"
+                    [ -n "${seen[$nested]:-}" ] && continue
+                    seen[$nested]=1
+                    echo "$nested"
+                done
+            fi
+        done
+    done
+    for label in "${!TARGETS[@]}"; do
+        local dir="${TARGETS[$label]}"
+        dir_exists "$dir" || continue
+        for d in "$dir"/*/; do
+            [ -d "$d" ] || continue
+            local n
+            n=$(basename "$d")
+            if [ -f "$d/SKILL.md" ]; then
+                [ -n "${seen[$n]:-}" ] && continue
+                seen[$n]=1
+                echo "$n"
+            else
+                for sub in "$d"*/; do
+                    [ -d "$sub" ] || continue
+                    [ -f "$sub/SKILL.md" ] || continue
+                    local sn nested
+                    sn=$(basename "$sub")
+                    nested="$n/$sn"
+                    [ -n "${seen[$nested]:-}" ] && continue
+                    seen[$nested]=1
+                    echo "$nested"
+                done
+            fi
+        done
+    done
+}
+
+extract_frontmatter_field() {
+    local file="$1"
+    local field="$2"
+    [ -f "$file" ] || return 1
+    awk -v field="$field" '
+        BEGIN { found=0; block=""; is_block=0 }
+        /^---$/ {
+            if (found && is_block) { print block; exit }
+            in_fm = !in_fm; next
+        }
+        in_fm && !found && $0 ~ "^"field":" {
+            val = $0
+            sub("^"field":\\s*", "", val)
+            if (val == ">" || val == ">-" || val == "|" || val == "|-") {
+                is_block = 1; found = 1; next
+            }
+            gsub(/^["'\'']|["'\'']$/, "", val)
+            if (val == ">") val = ""
+            print val
+            exit
+        }
+        found && is_block && /^[ \t]/ {
+            line = $0; sub(/^[ \t]+/, "", line)
+            if (block == "") block = line
+            else block = block " " line
+            next
+        }
+        found && is_block && /^[^ \t]/ { print block; exit }
+        END { if (found && is_block) print block }
+    ' "$file"
+}
+
+has_frontmatter() {
+    local file="$1"
+    [ -f "$file" ] || return 1
+    head -1 "$file" 2>/dev/null | grep -q '^---$'
+}
+
+# -- Manifest --
+
+ensure_manifest() {
+    mkdir -p "$CONFIG_DIR"
+    if [ ! -f "$MANIFEST" ]; then
+        cmd_init
+    fi
+}
+
+manifest_get_field() {
+    local name="$1" field="$2"
+    [ -f "$MANIFEST" ] || return 1
+    awk -F'|' -v name="$name" -v field="$field" '
+        NR <= 4 { next }
+        { gsub(/[ \t]+/, "", $1); gsub(/[ \t]+/, "", $2); gsub(/[ \t]+/, "", $3) }
+        $1 == name {
+            if (field == "source") print $2
+            else if (field == "targets") print $3
+            exit
+        }
+    ' "$MANIFEST"
+}
+
+manifest_has() {
+    local name="$1"
+    [ -f "$MANIFEST" ] || return 1
+    awk -F'|' -v name="$name" '
+        NR <= 4 { next }
+        { gsub(/[ \t]+/, "", $1) }
+        $1 == name { found=1; exit }
+        END { exit !found }
+    ' "$MANIFEST"
+}
+
+manifest_add() {
+    local name="$1" source="$2" targets="$3"
+    ensure_manifest
+    if manifest_has "$name"; then
+        local tmp
+        tmp=$(mktemp)
+        awk -F'|' -v name="$name" -v src="$source" -v tgt="$targets" '
+            NR <= 4 { print; next }
+            { gsub(/[ \t]+/, "", $1) }
+            $1 == name { printf "%-30s | %-10s | %s\n", name, src, tgt; next }
+            { print }
+        ' "$MANIFEST" > "$tmp"
+        mv "$tmp" "$MANIFEST"
+    else
+        printf "%-30s | %-10s | %s\n" "$name" "$source" "$targets" >> "$MANIFEST"
+    fi
+}
+
+manifest_remove() {
+    local name="$1"
+    [ -f "$MANIFEST" ] || return 0
+    local tmp
+    tmp=$(mktemp)
+    awk -F'|' -v name="$name" '
+        NR <= 4 { print; next }
+        { gsub(/[ \t]+/, "", $1) }
+        $1 != name { print }
+    ' "$MANIFEST" > "$tmp"
+    mv "$tmp" "$MANIFEST"
+}
+
+
+
+cmd_init() {
+    mkdir -p "$CONFIG_DIR"
+    echo "# skill-sync manifest" > "$MANIFEST"
+    echo "# Format: skill_name | source | targets" >> "$MANIFEST"
+    echo "# Sources: agents, opencode, codex | Targets: claude (or - for canonical-only)" >> "$MANIFEST"
+    echo "#" >> "$MANIFEST"
+
+    # Build from current state
+    local added=0
+    for name in $(all_skill_names | sort); do
+        local src
+        src=$(source_for_skill "$name" 2>/dev/null || echo "orphan")
+
+        # Determine targets: which target dirs contain this skill
+        local tgt_list="-"
+        for tlabel in "${!TARGETS[@]}"; do
+            local tdir="${TARGETS[$tlabel]}"
+            if dir_exists "$tdir/$name"; then
+                if [ "$tgt_list" = "-" ]; then
+                    tgt_list="$tlabel"
+                else
+                    tgt_list="$tgt_list,$tlabel"
+                fi
+            fi
+        done
+
+        # Skip codex system skills
+        [ "$src" = "codex" ] && {
+            local cdir="${SOURCES[codex]}"
+            [ -d "$cdir/.system/$name" ] && continue
+        }
+
+        printf "%-30s | %-10s | %s\n" "$name" "$src" "$tgt_list" >> "$MANIFEST"
+        added=$((added + 1))
+    done
+
+    echo "Manifest generated: $MANIFEST"
+    echo "  $added skills indexed"
+}
+
+cmd_sync_all() {
+    ensure_manifest
+    local total=0 synced=0 updated=0 failed=0
+
+    echo "Syncing all manifest skills..."
+    echo ""
+
+    while IFS='|' read -r name source targets; do
+        # Skip comments/headers
+        name=$(echo "$name" | xargs)
+        [[ "$name" =~ ^# ]] && continue
+        [ -z "$name" ] && continue
+        source=$(echo "$source" | xargs)
+        targets=$(echo "$targets" | xargs)
+        [ "$targets" = "-" ] && continue
+
+        total=$((total + 1))
+
+        local src_path
+        src_path=$(source_path_for_skill "$name") || {
+            echo "  ⚠️  $name — source not found"
+            failed=$((failed + 1))
+            continue
+        }
+
+        # Sync to each target
+        IFS=',' read -ra tgt_arr <<< "$targets"
+        for tlabel in "${tgt_arr[@]}"; do
+            tlabel=$(echo "$tlabel" | xargs)
+            local tdir="${TARGETS[$tlabel]}"
+            [ -d "$tdir" ] || mkdir -p "$tdir"
+
+            local src_hash tgt_hash
+            src_hash=$(md5_content "$src_path")
+            if [ -d "$tdir/$name" ]; then
+                tgt_hash=$(md5_content "$tdir/$name")
+            else
+                tgt_hash="none"
+            fi
+
+            if [ "$src_hash" = "$tgt_hash" ]; then
+                echo "  ✅ $name → $tlabel (in sync)"
+                synced=$((synced + 1))
+            else
+                _safe_rm "$tdir/$name"
+                _safe_cp "$src_path" "$tdir/$name"
+                echo "  🔄 $name → $tlabel (updated)"
+                updated=$((updated + 1))
+            fi
+        done
+    done < "$MANIFEST"
+
+    echo ""
+    echo "Done: $total skills, $updated updated, $synced already in sync, $failed failed"
+}
+
+cmd_sync_one() {
+    local name="$1"
+    ensure_manifest
+
+    local targets
+    targets=$(manifest_get_field "$name" "targets")
+    [ -z "$targets" ] && {
+        echo "'$name' not in manifest. Use: skill-sync add $name"
+        return 1
+    }
+    [ "$targets" = "-" ] && {
+        echo "'$name' has no sync targets (canonical-only)."
+        return 0
+    }
+
+    local src_path
+    src_path=$(source_path_for_skill "$name") || {
+        echo "Source not found for '$name'"
+        return 1
+    }
+
+    IFS=',' read -ra tgt_arr <<< "$targets"
+    for tlabel in "${tgt_arr[@]}"; do
+        tlabel=$(echo "$tlabel" | xargs)
+        local tdir="${TARGETS[$tlabel]}"
+        [ -d "$tdir" ] || mkdir -p "$tdir"
+
+        if [ -d "$tdir/$name" ] && [ "$(md5_content "$src_path")" = "$(md5_content "$tdir/$name")" ]; then
+            echo "✅ $name → $tlabel (already in sync)"
+        else
+            _safe_rm "$tdir/$name"
+            _safe_cp "$src_path" "$tdir/$name"
+            echo "🔄 $name → $tlabel (updated)"
+        fi
+    done
+}
+
+cmd_add() {
+    local name="$1"
+    shift || true
+    local to_target="claude"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --to) to_target="$2"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    local src_label
+    src_label=$(source_for_skill "$name" 2>/dev/null) || {
+        echo "Skill '$name' not found in any source:"
+        for l in "${SOURCE_PRIORITY[@]}"; do echo "  ${SOURCES[$l]}/$name/"; done
+        return 1
+    }
+
+    local src_path
+    src_path=$(source_path_for_skill "$name")
+
+    local tdir="${TARGETS[$to_target]}"
+    [ -d "$tdir" ] || mkdir -p "$tdir"
+
+    _safe_rm "$tdir/$name"
+    _safe_cp "$src_path" "$tdir/$name"
+
+    manifest_add "$name" "$src_label" "$to_target"
+    echo "✅ '$name' added → $to_target (from $src_label)"
+}
+
+cmd_remove() {
+    local name="$1"
+    shift || true
+    local from_target="" purge=0
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --from) from_target="$2"; shift 2 ;;
+            --purge) purge=1; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    # Safety: resolve the skill and show where it currently exists
+    local src_label="" src_path=""
+    src_label=$(source_for_skill "$name" 2>/dev/null) && src_path=$(source_path_for_skill "$name")
+
+    echo "Removing: $name"
+    echo ""
+
+    # Show current state
+    if [ -n "$src_path" ]; then
+        echo "  Source: $src_label ($src_path)"
+    else
+        echo "  Source: — (no canonical source)"
+    fi
+
+    local target_hits=""
+    for tlabel in "${!TARGETS[@]}"; do
+        if [ -d "${TARGETS[$tlabel]}/$name" ]; then
+            target_hits="$target_hits $tlabel"
+        fi
+    done
+    if [ -n "$target_hits" ]; then
+        echo "  Targets:$target_hits"
+    else
+        echo "  Targets: — (not deployed)"
+    fi
+    echo ""
+
+    # If skill doesn't exist anywhere
+    if [ -z "$src_path" ] && [ -z "$target_hits" ]; then
+        echo "Skill '$name' not found anywhere."
+        manifest_remove "$name"
+        return 0
+    fi
+
+    # Phase 1: Remove from targets
+    local removed_any=0
+
+    if [ -n "$from_target" ]; then
+        # Remove from specific target only
+        local tdir="${TARGETS[$from_target]:-}"
+        if [ -z "$tdir" ]; then
+            echo "Unknown target '$from_target'"
+            return 1
+        fi
+        if [ -d "$tdir/$name" ]; then
+            _safe_rm "$tdir/$name"
+            echo "  🗑️  Removed from $from_target"
+            removed_any=1
+        else
+            echo "  '$name' was not in $from_target"
+        fi
+
+        # Update manifest: remove this target from the list
+        local current_targets
+        current_targets=$(manifest_get_field "$name" "targets")
+        local new_targets=""
+        IFS=',' read -ra remain <<< "$current_targets"
+        for t in "${remain[@]}"; do
+            t=$(echo "$t" | xargs)
+            [ "$t" = "$from_target" ] && continue
+            if [ -z "$new_targets" ]; then new_targets="$t"; else new_targets="$new_targets,$t"; fi
+        done
+        [ -z "$new_targets" ] && new_targets="-"
+        [ -n "$src_label" ] && manifest_add "$name" "$src_label" "$new_targets"
+    else
+        # Remove from ALL targets
+        for tlabel in "${!TARGETS[@]}"; do
+            local tdir="${TARGETS[$tlabel]}"
+            if [ -d "$tdir/$name" ]; then
+                _safe_rm "$tdir/$name"
+                echo "  🗑️  Removed from $tlabel"
+                removed_any=1
+            fi
+        done
+        [ $removed_any -eq 0 ] && echo "  (was not deployed to any target)"
+
+        # Update manifest: set targets to -
+        [ -n "$src_label" ] && manifest_add "$name" "$src_label" "-"
+    fi
+
+    # Phase 2: Purge from canonical source
+    if [ $purge -eq 1 ]; then
+        if [ -n "$src_path" ] && [ -d "$src_path" ]; then
+            _safe_rm "$src_path"
+            echo "  💀 Purged from $src_label source"
+            manifest_remove "$name"
+        elif [ -z "$src_path" ]; then
+            echo "  (no canonical source to purge)"
+        fi
+    fi
+
+    echo ""
+    echo "Done."
+
+    # Show what remains
+    if [ $purge -eq 0 ] && [ -n "$src_label" ]; then
+        echo "  Skill still exists in source: $src_label"
+        echo "  Re-deploy with: skill-sync add $name"
+    elif [ $purge -eq 1 ]; then
+        echo "  Skill fully removed from all locations."
+    fi
+}
+
+
+cmd_create() {
+    local name="$1"
+    shift || true
+    local scope="agents"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --scope) scope="$2"; shift 2 ;;
+            --to)
+                local to_target="$2"; shift 2
+                ;;
+            *) shift ;;
+        esac
+    done
+
+    # Validate scope
+    [ -z "${SOURCES[$scope]:-}" ] && {
+        echo "Unknown scope '$scope'. Use: agents, opencode, codex"
+        return 1
+    }
+
+    local dir="${SOURCES[$scope]}/$name"
+    [ -d "$dir" ] && {
+        echo "'$name' already exists at $dir"
+        return 1
+    }
+
+    mkdir -p "$dir"
+    cat > "$dir/SKILL.md" << EOF
+---
+name: $name
+description: TODO — describe what this skill does and when to trigger it. Include specific use cases and example phrases the user might say.
+---
+
+# $(echo "$name" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++)$i=toupper(substr($i,1,1))substr($i,2)}1')
+
+## When to Use
+
+TODO — Describe the specific scenarios where this skill should be triggered.
+
+## Workflow
+
+TODO — Describe the step-by-step process.
+
+## Key Rules
+
+TODO — List any non-negotiable rules or constraints.
+EOF
+
+    manifest_add "$name" "$scope" "-"
+    echo "✅ Created '$name' in $scope"
+    echo "   $dir/SKILL.md"
+    echo ""
+    echo "   Edit the SKILL.md, then deploy with:"
+    echo "   skill-sync add $name --to claude"
+}
+
+cmd_edit() {
+    local name="$1"
+    local src_path
+    src_path=$(source_path_for_skill "$name") || {
+        echo "'$name' not found in any canonical source"
+        return 1
+    }
+
+    local skill_md="$src_path/SKILL.md"
+    [ -f "$skill_md" ] || {
+        echo "No SKILL.md at $src_path"
+        return 1
+    }
+
+    local editor="${EDITOR:-vi}"
+    echo "Opening $skill_md with $editor..."
+    "$editor" "$skill_md"
+
+    # After editor exits, offer to sync if skill has targets
+    local targets
+    targets=$(manifest_get_field "$name" "targets" 2>/dev/null)
+    if [ -n "$targets" ] && [ "$targets" != "-" ]; then
+        echo ""
+        echo "Skill '$name' has targets: $targets"
+        echo "Run 'skill-sync sync $name' to push changes."
+    fi
+}
+
+cmd_pull() {
+    local name="$1"
+    shift || true
+    local from_target=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --from) from_target="$2"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    local src_path
+    src_path=$(source_path_for_skill "$name") || {
+        echo "Canonical source for '$name' not found"
+        return 1
+    }
+
+    # Find which target to pull from
+    local tlabel tdir
+    if [ -n "$from_target" ]; then
+        tlabel="$from_target"
+        tdir="${TARGETS[$tlabel]:-}"
+        [ -z "$tdir" ] && { echo "Unknown target '$tlabel'"; return 1; }
+    else
+        # Auto-detect: find first target that has this skill
+        for tl in "${!TARGETS[@]}"; do
+            if [ -d "${TARGETS[$tl]}/$name" ]; then
+                tlabel="$tl"
+                tdir="${TARGETS[$tl]}"
+                break
+            fi
+        done
+    fi
+
+    [ -z "${tlabel:-}" ] && { echo "'$name' not found in any target"; return 1; }
+
+    if [ ! -d "$tdir/$name" ]; then
+        echo "'$name' not in $tlabel"
+        return 1
+    fi
+
+    local src_hash tgt_hash
+    src_hash=$(md5_content "$src_path")
+    tgt_hash=$(md5_content "$tdir/$name")
+
+    if [ "$src_hash" = "$tgt_hash" ]; then
+        echo "✅ Already in sync — no changes to pull"
+        return 0
+    fi
+
+    echo "Pulling '$name' from $tlabel → canonical source..."
+    _safe_rm "$src_path"
+    _safe_cp "$tdir/$name" "$src_path"
+    echo "✅ Pulled. Canonical source updated from $tlabel copy."
+    echo "   Run 'skill-sync sync' to push to other targets."
+}
+
+cmd_rename() {
+    local old_name="$1"
+    local new_name="$2"
+
+    [ -z "$new_name" ] && { echo "Usage: skill-sync rename <old> <new>"; return 1; }
+
+    # Validate new name
+    [[ "$new_name" =~ ^[a-z0-9][-a-z0-9/]*$ ]] || {
+        echo "Invalid name '$new_name' — use lowercase, hyphens, digits only"
+        return 1
+    }
+
+    local src_label src_path
+    src_label=$(source_for_skill "$old_name" 2>/dev/null) || {
+        echo "'$old_name' not found in any source"
+        return 1
+    }
+    src_path=$(source_path_for_skill "$old_name")
+
+    # Check new name doesn't already exist
+    if source_for_skill "$new_name" >/dev/null 2>&1; then
+        echo "'$new_name' already exists"
+        return 1
+    fi
+
+    echo "Renaming: $old_name → $new_name"
+    echo ""
+
+    # 1. Rename canonical source
+    local src_parent
+    src_parent=$(dirname "$src_path")
+    _safe_mv "$src_path" "$src_parent/$new_name"
+    echo "  📝 Renamed in $src_label source"
+
+    # 2. Rename in all targets
+    for tlabel in "${!TARGETS[@]}"; do
+        local tdir="${TARGETS[$tlabel]}"
+        if [ -d "$tdir/$old_name" ]; then
+            _safe_rm "$tdir/$old_name"
+            _safe_cp "$src_parent/$new_name" "$tdir/$new_name"
+            echo "  🔄 Updated in $tlabel"
+        fi
+    done
+
+    # 3. Update manifest
+    manifest_remove "$old_name"
+    local targets="-"
+    for tlabel in "${!TARGETS[@]}"; do
+        if [ -d "${TARGETS[$tlabel]}/$new_name" ]; then
+            [ "$targets" = "-" ] && targets="$tlabel" || targets="$targets,$tlabel"
+        fi
+    done
+    manifest_add "$new_name" "$src_label" "$targets"
+
+    echo ""
+    echo "✅ Renamed $old_name → $new_name across all locations"
+}
+
+cmd_info() {
+    local name="$1"
+
+    local src_label
+    src_label=$(source_for_skill "$name" 2>/dev/null) || {
+        echo "'$name' not found in any canonical source"
+        # Check if it's orphaned in a target
+        for tlabel in "${!TARGETS[@]}"; do
+            if [ -d "${TARGETS[$tlabel]}/$name" ]; then
+                echo "  ⚠️  Found orphaned copy in $tlabel (no canonical source)"
+            fi
+        done
+        return 1
+    }
+
+    local src_path
+    src_path=$(source_path_for_skill "$name")
+    local desc
+    desc=$(extract_frontmatter_field "$src_path/SKILL.md" "description")
+    [ -z "$desc" ] && desc="(no description)"
+
+    echo "$name"
+    echo "  Source:     $src_label ($src_path)"
+    echo "  Description: $desc"
+
+    # Size and files
+    local size files
+    size=$(du -sh "$src_path" 2>/dev/null | cut -f1)
+    files=$(find "$src_path" -type f | wc -l)
+    echo "  Files:      $files ($size)"
+
+    # Frontmatter health
+    if has_frontmatter "$src_path/SKILL.md"; then
+        echo "  Frontmatter: ✅ present"
+    else
+        echo "  Frontmatter: ❌ MISSING"
+    fi
+
+    # Targets / sync state
+    local manifest_targets="-"
+    [ -f "$MANIFEST" ] && manifest_targets=$(manifest_get_field "$name" "targets")
+    [ -z "$manifest_targets" ] && manifest_targets="(not in manifest)"
+    echo "  Manifest:   $manifest_targets"
+
+    echo "  Copies:"
+    for tlabel in "${!TARGETS[@]}"; do
+        local tdir="${TARGETS[$tlabel]}"
+        if [ -d "$tdir/$name" ]; then
+            local sh th
+            sh=$(md5_content "$src_path")
+            th=$(md5_content "$tdir/$name")
+            if [ "$sh" = "$th" ]; then
+                echo "    $tlabel: ✅ in sync"
+            else
+                echo "    $tlabel: 🔄 DRIFTED"
+            fi
+        else
+            echo "    $tlabel: — (not deployed)"
+        fi
+    done
+}
+
+cmd_status() {
+    ensure_manifest
+    printf "%-30s %-10s %-15s %s\n" "SKILL" "SOURCE" "TARGETS" "STATE"
+    printf "%-30s %-10s %-15s %s\n" "$(printf '%.0s-' {1..30})" "$(printf '%.0s-' {1..10})" "$(printf '%.0s-' {1..15})" "$(printf '%.0s-' {1..5})"
+
+    local all_ok=1
+
+    while IFS='|' read -r name source targets; do
+        name=$(echo "$name" | xargs)
+        [[ "$name" =~ ^# ]] && continue
+        [ -z "$name" ] && continue
+        source=$(echo "$source" | xargs)
+        targets=$(echo "$targets" | xargs)
+
+        local state=""
+        if [ "$targets" = "-" ]; then
+            state="canonical"
+        else
+            IFS=',' read -ra tgt_arr <<< "$targets"
+            for tlabel in "${tgt_arr[@]}"; do
+                tlabel=$(echo "$tlabel" | xargs)
+                local tdir="${TARGETS[$tlabel]}"
+                local src_path
+                src_path=$(source_path_for_skill "$name" 2>/dev/null)
+                if [ -z "$src_path" ]; then
+                    state="$state ⚠️"
+                    all_ok=0
+                elif [ -d "$tdir/$name" ]; then
+                    if [ "$(md5_content "$src_path")" = "$(md5_content "$tdir/$name")" ]; then
+                        state="$state ✅"
+                    else
+                        state="$state 🔄"
+                        all_ok=0
+                    fi
+                else
+                    state="$state ❌"
+                    all_ok=0
+                fi
+            done
+        fi
+
+        printf "%-30s %-10s %-15s %s\n" "$name" "$source" "$targets" "$state"
+    done < "$MANIFEST"
+
+    echo ""
+    [ $all_ok -eq 1 ] && echo "All synced ✅" || echo "Issues found — run 'skill-sync sync' to fix"
+}
+
+cmd_list() {
+    local show_all="${1:-}"
+
+    if [ "$show_all" != "--all" ]; then
+        # List manifest skills only
+        ensure_manifest
+        printf "%-30s %-10s %s\n" "SKILL" "SOURCE" "TARGETS"
+        printf "%-30s %-10s %s\n" "-----" "------" "-------"
+        while IFS='|' read -r name source targets; do
+            name=$(echo "$name" | xargs)
+            [[ "$name" =~ ^# ]] && continue
+            [ -z "$name" ] && continue
+            source=$(echo "$source" | xargs)
+            targets=$(echo "$targets" | xargs)
+            [ "$targets" != "-" ] && printf "%-30s %-10s %s\n" "$name" "$source" "$targets"
+        done < "$MANIFEST"
+        return
+    fi
+
+    # List ALL skills from all locations
+    printf "%-30s %-10s %-10s %s\n" "SKILL" "SOURCE" "COPIES" "DESCRIPTION"
+    printf "%-30s %-10s %-10s %s\n" "-----" "------" "------" "-----------"
+
+    for name in $(all_skill_names | sort); do
+        local src_label src_path copies=""
+        src_label=$(source_for_skill "$name" 2>/dev/null) || src_label="orphan"
+        src_path=$(source_path_for_skill "$name" 2>/dev/null) || src_path=""
+
+        for tlabel in "${!TARGETS[@]}"; do
+            [ -d "${TARGETS[$tlabel]}/$name" ] && copies="$copies $tlabel"
+        done
+        [ -z "$copies" ] && copies="-"
+
+        local desc=""
+        if [ -n "$src_path" ] && [ -f "$src_path/SKILL.md" ]; then
+            desc=$(extract_frontmatter_field "$src_path/SKILL.md" "description" 2>/dev/null)
+        fi
+        [ -z "$desc" ] && desc="—"
+
+        printf "%-30s %-10s %-10s %.60s\n" "$name" "$src_label" "$copies" "$desc"
+    done
+}
+
+cmd_search() {
+    local query="$*"
+    [ -z "$query" ] && { echo "Usage: skill-sync search <query>"; return 1; }
+    query=$(echo "$query" | tr '[:upper:]' '[:lower:]')
+
+    printf "%-30s %-10s %.70s\n" "SKILL" "SOURCE" "DESCRIPTION"
+    printf "%-30s %-10s %.70s\n" "-----" "------" "-----------"
+
+    local found=0
+    for name in $(all_skill_names | sort); do
+        local src_path desc lname
+        src_path=$(source_path_for_skill "$name" 2>/dev/null) || continue
+        desc=$(extract_frontmatter_field "$src_path/SKILL.md" "description" 2>/dev/null)
+        [ -z "$desc" ] && desc="—"
+        lname=$(echo "$name $desc" | tr '[:upper:]' '[:lower:]')
+
+        if [[ "$lname" == *"$query"* ]]; then
+            local src_label
+            src_label=$(source_for_skill "$name")
+            printf "%-30s %-10s %.70s\n" "$name" "$src_label" "$desc"
+            found=$((found + 1))
+        fi
+    done
+
+    echo ""
+    [ $found -eq 0 ] && echo "No matches for '$query'" || echo "$found skill(s) found"
+}
+
+cmd_diff() {
+    local name="$1"
+
+    local src_path
+    src_path=$(source_path_for_skill "$name") || {
+        echo "'$name' not found in any source"
+        return 1
+    }
+
+    local has_targets=0
+    for tlabel in "${!TARGETS[@]}"; do
+        if [ -d "${TARGETS[$tlabel]}/$name" ]; then
+            has_targets=1
+            echo "── diff: $name (source → $tlabel) ──"
+            diff -rq "$src_path" "${TARGETS[$tlabel]}/$name" 2>/dev/null || true
+            echo ""
+
+            # Show SKILL.md content diff if different
+            if ! diff -q "$src_path/SKILL.md" "${TARGETS[$tlabel]}/$name/SKILL.md" >/dev/null 2>&1; then
+                echo "── SKILL.md content diff ──"
+                diff -u "${TARGETS[$tlabel]}/$name/SKILL.md" "$src_path/SKILL.md" 2>/dev/null || true
+                echo ""
+            fi
+        fi
+    done
+
+    [ $has_targets -eq 0 ] && echo "'$name' has no target copies to diff against"
+}
+
+
+cmd_validate() {
+    local name="${1:-}"
+    local errors=0
+
+    if [ -n "$name" ]; then
+        local src_path
+        src_path=$(source_path_for_skill "$name" 2>/dev/null) || {
+            echo "❌ '$name' not found"
+            return 1
+        }
+        _validate_skill "$name" "$src_path"
+        return $?
+    fi
+
+    # Validate all
+    for n in $(all_skill_names | sort); do
+        local sp
+        sp=$(source_path_for_skill "$n" 2>/dev/null) || continue
+        _validate_skill "$n" "$sp" || errors=$((errors + 1))
+    done
+    echo ""
+    [ $errors -eq 0 ] && echo "All skills valid ✅" || echo "$errors skills have issues"
+}
+
+_validate_skill() {
+    local name="$1" path="$2"
+    local file="$path/SKILL.md"
+    local ok=1
+
+    [ -f "$file" ] || { echo "❌ $name — no SKILL.md"; return 1; }
+
+    has_frontmatter "$file" || { echo "❌ $name — missing YAML frontmatter (---)"; return 1; }
+
+    local fm_name fm_desc
+    fm_name=$(extract_frontmatter_field "$file" "name")
+    fm_desc=$(extract_frontmatter_field "$file" "description")
+
+    [ -z "$fm_name" ] && { echo "❌ $name — missing 'name' in frontmatter"; ok=0; }
+    [ -z "$fm_desc" ] && { echo "❌ $name — missing 'description' in frontmatter"; ok=0; }
+
+    # Check naming: lowercase, hyphens, digits only
+    [[ "$name" =~ ^[a-z0-9][-a-z0-9/]*$ ]] || { echo "⚠️  $name — name should be lowercase-hyphenated"; ok=0; }
+
+    # Check description length
+    if [ -n "$fm_desc" ]; then
+        local dlen=${#fm_desc}
+        [ $dlen -lt 20 ] && { echo "⚠️  $name — description very short ($dlen chars)"; ok=0; }
+    fi
+
+    [ $ok -eq 1 ] && echo "✅ $name"
+    return $(( 1 - ok ))
+}
+
+cmd_doctor() {
+    echo "Skill system health check"
+    echo ""
+    local issues=0
+
+    echo "── Frontmatter & naming ──"
+    cmd_validate || issues=$((issues + 1))
+
+    echo ""
+    echo "── Orphaned copies (in targets but no source) ──"
+    for tlabel in "${!TARGETS[@]}"; do
+        local tdir="${TARGETS[$tlabel]}"
+        dir_exists "$tdir" || continue
+        for d in "$tdir"/*/; do
+            [ -d "$d" ] || continue
+            local n
+            n=$(basename "$d")
+            if [ -f "$d/SKILL.md" ]; then
+                if ! source_for_skill "$n" >/dev/null 2>&1; then
+                    echo "  ⚠️  $n — in $tlabel but no canonical source"
+                    issues=$((issues + 1))
+                fi
+            else
+                for sub in "$d"*/; do
+                    [ -d "$sub" ] || continue
+                    [ -f "$sub/SKILL.md" ] || continue
+                    local sn nested
+                    sn=$(basename "$sub")
+                    nested="$n/$sn"
+                    if ! source_for_skill "$nested" >/dev/null 2>&1; then
+                        echo "  ⚠️  $nested — in $tlabel but no canonical source"
+                        issues=$((issues + 1))
+                    fi
+                done
+            fi
+        done
+    done
+    [ $issues -eq 0 ] && echo "  None ✅"
+
+    echo ""
+    echo "── Sync drift ──"
+    local drift=0
+    for tlabel in "${!TARGETS[@]}"; do
+        local tdir="${TARGETS[$tlabel]}"
+        dir_exists "$tdir" || continue
+        for d in "$tdir"/*/; do
+            [ -d "$d" ] || continue
+            local n
+            n=$(basename "$d")
+            local src_path
+            src_path=$(source_path_for_skill "$n" 2>/dev/null) || continue
+            if [ "$(md5_content "$src_path")" != "$(md5_content "$d")" ]; then
+                echo "  🔄 $n — drifted in $tlabel"
+                drift=$((drift + 1))
+            fi
+        done
+    done
+    [ $drift -eq 0 ] && echo "  All in sync ✅"
+
+    echo ""
+    echo "── Location summary ──"
+    for label in "${SOURCE_PRIORITY[@]}"; do
+        local dir="${SOURCES[$label]}"
+        if dir_exists "$dir"; then
+            local count
+            count=$(find "$dir" -maxdepth 1 -mindepth 1 -type d ! -name ".system" | wc -l)
+            printf "  %-12s %2d skills  %s\n" "$label" "$count" "$dir"
+        fi
+    done
+    for tlabel in "${!TARGETS[@]}"; do
+        local tdir="${TARGETS[$tlabel]}"
+        if dir_exists "$tdir"; then
+            local count
+            count=$(find "$tdir" -maxdepth 1 -mindepth 1 -type d | wc -l)
+            printf "  %-12s %2d skills  %s\n" "$tlabel" "$count" "$tdir"
+        fi
+    done
+
+    echo ""
+    local total_issues=$((issues + drift))
+    [ $total_issues -eq 0 ] && echo "All healthy ✅" || echo "$total_issues total issues found"
+}
+
+
+# ── Config file writer ─────────────────────────────────────────
+
+_save_config() {
+    mkdir -p "$CONFIG_DIR"
+    {
+        echo "# Auto-generated by skill-sync."
+        echo "# This file is sourced at startup. Edit manually or use target commands."
+        echo ""
+        declare -p SOURCES
+        declare -p TARGETS
+        declare -p SOURCE_PRIORITY
+    } > "$CONFIG_FILE"
+}
+
+# ── New commands ───────────────────────────────────────────────
+
+cmd_target() {
+    local action="${1:-list}"
+
+    case "$action" in
+        list)
+            echo "Sync targets:"
+            echo ""
+            printf "%-15s %s\n" "LABEL" "PATH"
+            printf "%-15s %s\n" "-----" "----"
+            for tlabel in "${!TARGETS[@]}"; do
+                printf "%-15s %s\n" "$tlabel" "${TARGETS[$tlabel]}"
+            done
+            echo ""
+            echo "Sources:"
+            printf "%-15s %s\n" "LABEL" "PATH"
+            printf "%-15s %s\n" "-----" "----"
+            for slabel in "${SOURCE_PRIORITY[@]}"; do
+                printf "%-15s %s\n" "$slabel" "${SOURCES[$slabel]}"
+            done
+            ;;
+        add)
+            local label="$2" path="$3"
+            [ -z "$label" ] || [ -z "$path" ] && {
+                echo "Usage: skill-sync target add <label> <path>"
+                return 1
+            }
+            # Expand ~ in path
+            path="${path/#\~/$HOME}"
+            [ -n "${TARGETS[$label]:-}" ] && {
+                echo "Target '$label' already exists: ${TARGETS[$label]}"
+                return 1
+            }
+            TARGETS["$label"]="$path"
+            mkdir -p "$path"
+            _save_config
+            echo "✅ Added target '$label' → $path"
+            echo "   Config saved to $CONFIG_FILE"
+            ;;
+        remove)
+            local label="$2"
+            [ -z "$label" ] && { echo "Usage: skill-sync target remove <label>"; return 1; }
+            [ -z "${TARGETS[$label]:-}" ] && {
+                echo "Target '$label' not found"
+                return 1
+            }
+            unset "TARGETS[$label]"
+            _save_config
+            echo "🗑️  Removed target '$label'"
+            echo "   (skill directories untouched, config updated)"
+            ;;
+        *)
+            echo "Usage: skill-sync target [list|add|remove]"
+            return 1
+            ;;
+    esac
+}
+
+
+# ── Main dispatch ──────────────────────────────────────────────
+
+# Parse global flags
+local_args=()
+for a in "$@"; do
+    case "$a" in
+        --dry-run) DRY_RUN=1 ;;
+        *) local_args+=("$a") ;;
+    esac
+done
+set -- "${local_args[@]}" 2>/dev/null || true
+[ $DRY_RUN -eq 1 ] && echo "[dry-run mode — no changes will be made]"
+
+cmd="${1:-help}"
+shift || true
+
+case "$cmd" in
+    sync|"")
+        [ -n "${1:-}" ] && cmd_sync_one "$1" || cmd_sync_all
+        ;;
+    add)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync add <name> [--to claude]"; exit 1; }
+        cmd_add "$@"
+        ;;
+    remove|rm)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync remove <name> [--from T] [--purge]"; exit 1; }
+        cmd_remove "$@"
+        ;;
+    create|new)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync create <name> [--scope agents|opencode]"; exit 1; }
+        cmd_create "$@"
+        ;;
+    edit)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync edit <name>"; exit 1; }
+        cmd_edit "$1"
+        ;;
+    pull)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync pull <name> [--from T]"; exit 1; }
+        cmd_pull "$@"
+        ;;
+    search)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync search <query>"; exit 1; }
+        cmd_search "$@"
+        ;;
+    rename)
+        [ -z "${2:-}" ] && { echo "Usage: skill-sync rename <old> <new>"; exit 1; }
+        cmd_rename "$1" "$2"
+        ;;
+    diff)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync diff <name>"; exit 1; }
+        cmd_diff "$1"
+        ;;
+    target)
+        cmd_target "${1:-list}" "${2:-}" "${3:-}"
+        ;;
+    info)
+        [ -z "${1:-}" ] && { echo "Usage: skill-sync info <name>"; exit 1; }
+        cmd_info "$1"
+        ;;
+    status)
+        cmd_status
+        ;;
+    list|ls)
+        cmd_list "${1:-}"
+        ;;
+    validate|check)
+        cmd_validate "${1:-}"
+        ;;
+    doctor)
+        cmd_doctor
+        ;;
+    init)
+        cmd_init
+        ;;
+    help|--help|-h)
+        cat << 'HELPEOF'
+skill-sync — manage skills across all AI agent directories
+
+Commands:
+  sync [name]              Sync all manifest skills, or just one
+  add <name> [--to T]      Deploy a skill to a target (default: claude)
+  remove <name>            Remove from targets (--from T) or --purge source
+  create <name> [--scope S]  Scaffold new skill (default scope: agents)
+  edit <name>              Open SKILL.md in $EDITOR, then offer to sync
+  pull <name> [--from T]   Reverse sync: copy target edits back to source
+  search <query>           Find skills by keyword in name or description
+  rename <old> <new>       Rename a skill across all locations
+  diff <name>              Show content diff between source and target copies
+  info <name>              Show details, sync state, and health
+  status                   Show sync status for all tracked skills
+  list [--all]             List synced skills, or --all for every skill
+  validate [name]          Check frontmatter + naming (one or all)
+  doctor                   Full health check across all locations
+  target [list|add|remove]  Manage sync targets dynamically
+  init                     Generate manifest from current state
+
+Global flags:
+  --dry-run                Preview changes without executing
+
+Sources (canonical, auto-discovered):
+  agents     ~/.agents/skills/
+  opencode   ~/.config/opencode/skills/
+  codex      ~/.codex/skills/
+
+Targets (real copies, synced from sources):
+  claude     ~/.claude/skills/
+
+Config: ~/.config/skill-sync/config
+Manifest: ~/.config/skill-sync/manifest
+HELPEOF
+        ;;
+    *)
+        echo "Unknown command: $cmd"
+        echo "Run 'skill-sync help' for usage"
+        exit 1
+        ;;
+esac