Initial commit

.gitignore

@@ -0,0 +1 @@
+.DS_Store

skillshare/.skillshare-meta.json

@@ -0,0 +1,8 @@
+{
+  "source": "github.com/runkids/skillshare/skills/skillshare",
+  "type": "github-subdir",
+  "installed_at": "2026-01-31T18:20:04.489840917-05:00",
+  "repo_url": "https://github.com/runkids/skillshare.git",
+  "subdir": "skills/skillshare",
+  "version": "0355d36"
+}

skillshare/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: skillshare
+version: 0.8.1
+description: Syncs skills across AI CLI tools from a single source of truth. Use when asked to "sync skills", "collect skills", "pull from remote", "show status", "list skills", "install skill", "initialize skillshare", "search skills", or manage skill targets.
+argument-hint: "[command] [target] [--dry-run]"
+---
+
+# Skillshare CLI
+
+```
+Source: ~/.config/skillshare/skills  ← Single source of truth
+         ↓ sync (symlinks)
+Targets: ~/.claude/skills, ~/.cursor/skills, ...
+```
+
+## Quick Start
+
+```bash
+skillshare status              # Check state
+skillshare sync --dry-run      # Preview
+skillshare sync                # Execute
+```
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| **Status** | `status`, `diff`, `list --verbose`, `doctor` |
+| **Sync** | `sync`, `sync --dry-run` |
+| **Create** | `new <name>` → `sync` |
+| **Search** | `search <query>`, `search --list`, `search --json` |
+| **Install** | `install <source>` → `sync` |
+| **Team repo** | `install <url> --track` → `sync` |
+| **Collect** | `collect <target>` → `sync` |
+| **Update** | `update <name>`, `update --all` → `sync` |
+| **Remove** | `uninstall <name>` → `sync` |
+| **Git sync** | `push -m "msg"`, `pull` |
+| **Targets** | `target add <n> <p>`, `target remove <n>`, `target <n> --mode merge\|symlink` |
+| **Upgrade** | `upgrade`, `upgrade --cli`, `upgrade --skill` |
+
+## Init (Non-Interactive)
+
+**AI must use flags** — cannot respond to CLI prompts.
+
+```bash
+# Step 1: Check existing skills
+ls ~/.claude/skills ~/.cursor/skills 2>/dev/null | head -10
+
+# Step 2: Run based on findings
+skillshare init --copy-from claude --all-targets --git  # If skills exist
+skillshare init --no-copy --all-targets --git           # Fresh start
+
+# Step 3: Verify
+skillshare status
+```
+
+**Add new agents later:**
+```bash
+skillshare init --discover --select "windsurf,kilocode"
+```
+
+See [init.md](references/init.md) for all flags.
+
+## Safety
+
+**NEVER** `rm -rf` symlinked skills — deletes source. Use `skillshare uninstall`.
+
+## References
+
+| Topic | File |
+|-------|------|
+| Init flags | [init.md](references/init.md) |
+| Sync/pull/push | [sync.md](references/sync.md) |
+| Install/update | [install.md](references/install.md) |
+| Status/diff/list | [status.md](references/status.md) |
+| Target management | [targets.md](references/targets.md) |
+| Backup/restore | [backup.md](references/backup.md) |
+| Troubleshooting | [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) |

skillshare/references/TROUBLESHOOTING.md

@@ -0,0 +1,61 @@
+# Troubleshooting
+
+## Quick Fixes
+
+| Problem | Solution |
+|---------|----------|
+| "config not found" | `skillshare init` |
+| Target shows differences | `skillshare sync` |
+| Lost source files | `cd ~/.config/skillshare/skills && git checkout -- .` |
+| Skill not appearing | `skillshare sync` after install |
+| Git push fails | `git remote add origin <url>` in source |
+
+## Recovery
+
+```bash
+skillshare doctor          # Diagnose
+skillshare backup          # Safety backup
+skillshare sync --dry-run  # Preview
+skillshare sync            # Fix
+```
+
+## Git Recovery
+
+```bash
+cd ~/.config/skillshare/skills
+git checkout -- <skill>/   # Restore specific
+git checkout -- .          # Restore all
+```
+
+## AI Assistant Notes
+
+### Symlink Safety
+
+- **merge mode** (default): Per-skill symlinks. Edit anywhere = edit source.
+- **symlink mode**: Entire directory symlinked.
+
+**Safe:** `skillshare uninstall`, `target remove`
+
+**DANGEROUS:** `rm -rf` on symlinked skills deletes source!
+
+### When to Use --dry-run
+
+- First-time users
+- Before `sync`, `collect --all`, `restore`
+- Before `install` from unknown sources
+
+### Init (Non-Interactive)
+
+AI cannot respond to CLI prompts. Always use flags:
+
+```bash
+skillshare init --copy-from claude --all-targets --git
+```
+
+### Debug Sync
+
+```bash
+skillshare status
+skillshare diff
+ls -la ~/.claude/skills  # Check symlinks
+```

skillshare/references/backup.md

@@ -0,0 +1,13 @@
+# Backup & Restore
+
+```bash
+skillshare backup                # All targets
+skillshare backup claude         # Specific target
+skillshare backup --list         # List backups
+skillshare backup --cleanup      # Remove old
+
+skillshare restore claude                            # Latest
+skillshare restore claude --from 2026-01-14_21-22   # Specific
+```
+
+Backups: `~/.config/skillshare/backups/<timestamp>/`

skillshare/references/init.md

@@ -0,0 +1,35 @@
+# Init Command
+
+**Source:** Always `~/.config/skillshare/skills` (use `--source` only if user explicitly requests).
+
+## Flags
+
+**Copy (mutually exclusive):**
+- `--copy-from <name|path>` — Import from target/path
+- `--no-copy` — Empty source
+
+**Targets (mutually exclusive):**
+- `--targets "claude,cursor"` — Specific list
+- `--all-targets` — All detected
+- `--no-targets` — Skip
+
+**Git (mutually exclusive):**
+- `--git` — Init git (recommended)
+- `--no-git` — Skip
+
+**Discover (add new agents):**
+- `--discover --select "windsurf,kilocode"` — Non-interactive (AI use this)
+- `--discover` — Interactive only (NOT for AI)
+
+**Other:**
+- `--source <path>` — Custom source (**only if user requests**)
+- `--remote <url>` — Set git remote
+- `--dry-run` — Preview
+
+## Examples
+
+```bash
+skillshare init --no-copy --all-targets --git           # Fresh start
+skillshare init --copy-from claude --all-targets --git  # Import from Claude
+skillshare init --discover --select "windsurf"          # Add new agents
+```

skillshare/references/install.md

@@ -0,0 +1,59 @@
+# Install, Update & Uninstall
+
+## install
+
+```bash
+# GitHub
+skillshare install owner/repo                    # Browse repo for skills
+skillshare install owner/repo/path/to/skill      # Direct path
+skillshare install git@github.com:user/repo.git  # SSH
+
+# Local
+skillshare install ~/Downloads/my-skill
+
+# Team repo (tracked for updates)
+skillshare install github.com/team/skills --track
+```
+
+| Flag | Description |
+|------|-------------|
+| `--name <n>` | Custom name |
+| `--force, -f` | Overwrite existing |
+| `--update, -u` | Update if exists |
+| `--track, -t` | Track for `update` |
+| `--dry-run, -n` | Preview |
+
+**Tracked repos:** Prefix `_`, nested `__` (e.g., `_team__frontend__ui`).
+
+After install: `skillshare sync`
+
+## update
+
+```bash
+skillshare update my-skill       # From stored source
+skillshare update _team-repo     # Git pull tracked repo
+skillshare update --all          # All tracked repos
+skillshare update _repo --force  # Discard local changes
+```
+
+After update: `skillshare sync`
+
+## uninstall
+
+```bash
+skillshare uninstall my-skill          # With confirmation
+skillshare uninstall my-skill --force  # Skip confirmation
+```
+
+After uninstall: `skillshare sync`
+
+## new
+
+Create a new skill template.
+
+```bash
+skillshare new <name>           # Create SKILL.md template
+skillshare new <name> --dry-run # Preview
+```
+
+After create: Edit SKILL.md → `skillshare sync`

skillshare/references/status.md

@@ -0,0 +1,62 @@
+# Status & Inspection Commands
+
+## status
+
+Shows source location, targets, and sync state.
+
+```bash
+skillshare status
+```
+
+## diff
+
+Shows differences between source and targets.
+
+```bash
+skillshare diff                # All targets
+skillshare diff claude         # Specific target
+```
+
+## list
+
+Lists installed skills.
+
+```bash
+skillshare list                # Basic list
+skillshare list --verbose      # With source and install info
+```
+
+## search
+
+Search GitHub for skills (repos with SKILL.md).
+
+```bash
+skillshare search <query>           # Interactive (select to install)
+skillshare search <query> --list    # List only, no install prompt
+skillshare search <query> --json    # JSON output for scripting
+skillshare search <query> -n 10     # Limit results (default: 20, max: 100)
+```
+
+**Requires GitHub auth** (gh CLI or `GITHUB_TOKEN` env var).
+
+## doctor
+
+Checks configuration health and diagnoses issues.
+
+```bash
+skillshare doctor
+```
+
+## upgrade
+
+Upgrades CLI binary and/or built-in skillshare skill.
+
+```bash
+skillshare upgrade              # Both CLI + skill
+skillshare upgrade --cli        # CLI only
+skillshare upgrade --skill      # Skill only
+skillshare upgrade --force      # Skip confirmation
+skillshare upgrade --dry-run    # Preview
+```
+
+After upgrading skill: `skillshare sync`

skillshare/references/sync.md

@@ -0,0 +1,49 @@
+# Sync, Collect, Pull & Push Commands
+
+| Type | Command | Direction |
+|------|---------|-----------|
+| **Local** | `sync` / `collect` | Source ↔ Targets |
+| **Remote** | `push` / `pull` | Source ↔ Git Remote |
+
+## sync
+
+```bash
+skillshare sync                # Execute
+skillshare sync --dry-run      # Preview
+skillshare sync --force        # Override conflicts
+```
+
+## collect
+
+Import skills from target(s) to source.
+
+```bash
+skillshare collect claude      # From specific target
+skillshare collect --all       # From all targets
+skillshare collect --dry-run   # Preview
+```
+
+## pull
+
+Git pull + sync to all targets.
+
+```bash
+skillshare pull                # Pull + sync
+skillshare pull --dry-run      # Preview
+```
+
+## push
+
+Git commit + push source.
+
+```bash
+skillshare push                # Default message
+skillshare push -m "message"   # Custom message
+skillshare push --dry-run      # Preview
+```
+
+## Workflows
+
+**Local:** Edit anywhere → `collect` → `sync`
+
+**Cross-machine:** Machine A: `push` → Machine B: `pull`

skillshare/references/targets.md

@@ -0,0 +1,22 @@
+# Target Management
+
+```bash
+skillshare target list                        # List targets
+skillshare target claude                      # Show info
+skillshare target add myapp ~/.myapp/skills   # Add custom
+skillshare target remove myapp                # Safe unlink
+```
+
+## Sync Modes
+
+```bash
+skillshare target claude --mode merge         # Per-skill symlinks (default)
+skillshare target claude --mode symlink       # Entire dir symlinked
+```
+
+| Mode | Local Skills | Behavior |
+|------|--------------|----------|
+| `merge` | Preserved | Individual symlinks |
+| `symlink` | Not possible | Single symlink |
+
+**Always use** `target remove` — never `rm -rf` on symlinked targets.

skillshare/scripts/run.sh

@@ -0,0 +1,135 @@
+#!/bin/sh
+# skillshare runner - npx-style execution without installation
+# Usage: curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/skills/skillshare/scripts/run.sh | sh -s -- [command] [args]
+# Or:    sh run.sh [command] [args]
+set -e
+
+REPO="runkids/skillshare"
+CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/skillshare"
+BIN_DIR="$CACHE_DIR/bin"
+BINARY="$BIN_DIR/skillshare"
+VERSION_FILE="$CACHE_DIR/.version"
+MAX_AGE=86400  # Check for updates every 24 hours
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+info() { printf "${CYAN}[skillshare]${NC} %s\n" "$1" >&2; }
+success() { printf "${GREEN}[skillshare]${NC} %s\n" "$1" >&2; }
+warn() { printf "${YELLOW}[skillshare]${NC} %s\n" "$1" >&2; }
+error() { printf "${RED}[skillshare]${NC} %s\n" "$1" >&2; exit 1; }
+
+# Detect OS
+detect_os() {
+  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+  case "$OS" in
+    darwin) OS="darwin" ;;
+    linux) OS="linux" ;;
+    mingw*|msys*|cygwin*) error "Windows is not supported via this script. Please download from GitHub releases." ;;
+    *) error "Unsupported OS: $OS" ;;
+  esac
+}
+
+# Detect architecture
+detect_arch() {
+  ARCH=$(uname -m)
+  case "$ARCH" in
+    x86_64|amd64) ARCH="amd64" ;;
+    arm64|aarch64) ARCH="arm64" ;;
+    *) error "Unsupported architecture: $ARCH" ;;
+  esac
+}
+
+# Get file modification time in seconds since epoch (cross-platform)
+get_file_age() {
+  if [ "$(uname -s)" = "Darwin" ]; then
+    stat -f %m "$1" 2>/dev/null || echo 0
+  else
+    stat -c %Y "$1" 2>/dev/null || echo 0
+  fi
+}
+
+# Check if we need to update (version file older than MAX_AGE)
+needs_update() {
+  [ ! -f "$VERSION_FILE" ] && return 0
+  [ ! -x "$BINARY" ] && return 0
+
+  file_time=$(get_file_age "$VERSION_FILE")
+  current_time=$(date +%s)
+  age=$((current_time - file_time))
+
+  [ "$age" -ge "$MAX_AGE" ]
+}
+
+# Get latest version from GitHub API
+get_latest_version() {
+  LATEST=$(curl -sL "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)
+  if [ -z "$LATEST" ]; then
+    error "Failed to get latest version. Check your internet connection."
+  fi
+  VERSION=${LATEST#v}
+}
+
+# Download and install to cache
+download_binary() {
+  detect_os
+  detect_arch
+  get_latest_version
+
+  URL="https://github.com/${REPO}/releases/download/${LATEST}/skillshare_${VERSION}_${OS}_${ARCH}.tar.gz"
+
+  info "Downloading skillshare ${VERSION} for ${OS}/${ARCH}..."
+
+  mkdir -p "$BIN_DIR"
+
+  TMP_DIR=$(mktemp -d)
+  trap "rm -rf $TMP_DIR" EXIT
+
+  if ! curl -sL "$URL" | tar xz -C "$TMP_DIR" 2>/dev/null; then
+    error "Failed to download. URL: $URL"
+  fi
+
+  if [ ! -f "$TMP_DIR/skillshare" ]; then
+    error "Binary not found in archive"
+  fi
+
+  mv "$TMP_DIR/skillshare" "$BINARY"
+  chmod +x "$BINARY"
+  echo "$VERSION" > "$VERSION_FILE"
+
+  success "Cached skillshare ${VERSION} at ${BIN_DIR}"
+}
+
+# Main logic
+main() {
+  # 1. Check if skillshare is already in PATH
+  if command -v skillshare >/dev/null 2>&1; then
+    exec skillshare "$@"
+  fi
+
+  # 2. Check cached binary
+  if [ -x "$BINARY" ]; then
+    if ! needs_update; then
+      exec "$BINARY" "$@"
+    fi
+
+    # Try to update, but fall back to cached version on failure
+    if download_binary 2>/dev/null; then
+      exec "$BINARY" "$@"
+    else
+      warn "Update check failed, using cached version"
+      touch "$VERSION_FILE"  # Reset timer
+      exec "$BINARY" "$@"
+    fi
+  fi
+
+  # 3. First run - download binary
+  download_binary
+  exec "$BINARY" "$@"
+}
+
+main "$@"