@vikasagarwal101/skill-sync 1.0.0

package/rules/skill-sync.md

@@ -0,0 +1,96 @@
+## Skill Management — `skill-sync`
+
+The controlled entrypoint for managing AI agent skills across all locations on this machine. Use it instead of manually copying skills between directories.
+
+### Where it lives
+
+- CLI: `~/.local/bin/skill-sync`
+- Manifest: `~/.config/skill-sync/manifest`
+- Config: `~/.config/skill-sync/config` (auto-generated, editable)
+
+### Canonical sources (where skills live)
+
+| Label | Path | Scanned by |
+|-------|------|-----------|
+| `agents` | `~/.agents/skills/` | OpenCode, Codex |
+| `opencode` | `~/.config/opencode/skills/` | OpenCode only |
+| `codex` | `~/.codex/skills/` | Codex only |
+
+### Sync targets (real copies, not symlinks)
+
+| Label | Path | Why |
+|-------|------|-----|
+| `claude` | `~/.claude/skills/` | Claude Code doesn't scan `.agents/` and breaks on symlinks |
+
+Add custom targets with `skill-sync target add <label> <path>`.
+
+### Quick reference
+
+```bash
+# Core sync
+skill-sync                    # sync all tracked skills
+skill-sync sync <name>        # sync one skill
+skill-sync add <name>         # deploy skill to claude + track
+skill-sync remove <name>      # remove from targets (--purge to delete source)
+skill-sync --dry-run sync     # preview what would change
+
+# Authoring
+skill-sync create <name>      # scaffold new skill (default: agents scope)
+skill-sync edit <name>        # open SKILL.md in $EDITOR
+skill-sync rename <old> <new> # rename across all locations
+
+# Inspection
+skill-sync info <name>        # show source, sync state, health
+skill-sync status             # sync state across all skills
+skill-sync list --all         # every skill from every location
+skill-sync search <query>     # find skills by keyword
+skill-sync diff <name>        # show diff between source and target
+
+# Health
+skill-sync validate           # check frontmatter health
+skill-sync doctor             # full system health check
+
+# Target management
+skill-sync target list        # show all sources and targets
+skill-sync target add X /path # add a new sync target
+skill-sync target remove X    # remove a target
+
+# Maintenance
+skill-sync init               # rebuild manifest from current state
+skill-sync pull <name>        # reverse sync: pull target edits back to source
+```
+
+### Golden rules for agents
+
+1. **Always create skills in a canonical source first** (`~/.agents/skills/` for shared, `~/.config/opencode/skills/` for opencode-only), never directly in `~/.claude/skills/`.
+2. **Use `skill-sync add` to deploy** — never `cp -r` manually, as it bypasses manifest tracking.
+3. **Run `skill-sync sync` after editing** any skill that has copies in `.claude/`.
+4. **Use `skill-sync edit <name>`** to open the canonical SKILL.md — it reminds you to sync after.
+5. **Run `skill-sync doctor`** to check system health if something seems wrong.
+6. **Never create skills without YAML frontmatter** — `skill-sync create` generates it automatically.
+7. **Claude Code cannot follow symlinks** — that's why `.claude/skills/` uses real copies synced by this tool.
+
+### Creating a new skill
+
+```bash
+skill-sync create my-skill --scope agents    # scaffold in shared location
+skill-sync edit my-skill                     # open in $EDITOR to write content
+skill-sync add my-skill --to claude          # deploy to Claude Code
+```
+
+### After editing a skill
+
+```bash
+skill-sync edit <name>    # opens canonical source in $EDITOR, reminds to sync
+skill-sync                # push changes to all targets
+skill-sync status         # verify everything is in sync
+```
+
+### Reverse sync (target → source)
+
+If a skill was edited directly in a target (e.g., Claude copy was hand-modified):
+
+```bash
+skill-sync pull <name>              # pull from first available target
+skill-sync pull <name> --from claude  # pull from specific target
+```

package/scripts/bundle.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# bundle.sh — generate bin/skill-sync.sh from lib/ modules + dispatch
+# Called by npm prepublishOnly/prepack hooks
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT="$SCRIPT_DIR/bin/skill-sync.sh"
+
+mkdir -p "$SCRIPT_DIR/bin"
+
+{
+    echo '#!/usr/bin/env bash'
+    echo 'set -euo pipefail'
+    echo ''
+    echo '# skill-sync (bundled by scripts/bundle.sh)'
+    echo '# Source: https://github.com/vikasagarwal101/skill-sync'
+    echo ''
+    for lib in core sync authoring inspect health targets; do
+        cat "$SCRIPT_DIR/lib/$lib.sh" 2>/dev/null || { echo "ERROR: lib/$lib.sh not found" >&2; exit 1; }
+        echo ''
+    done
+    # Dispatch (everything from Main dispatch onward)
+    awk '/^# ── Main dispatch/{p=1} p' "$SCRIPT_DIR/skill-sync"
+} > "$OUT"
+
+chmod +x "$OUT"
+echo "Bundled: $OUT ($(wc -l < "$OUT") lines)"

package/skill-sync

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# skill-sync — manage skills across all AI agent directories
+# Entry point: sources lib modules in dev mode, bundled for production
+
+# Source library modules (dev mode — install.sh bundles for production)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -d "$SCRIPT_DIR/lib" ]; then
+    for _lib in core sync authoring inspect health targets; do
+        source "$SCRIPT_DIR/lib/$_lib.sh"
+    done
+fi
+
+# ── 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