From 0970431d0ac6bd0256b13ab32c2896b8f0a82af8 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Sat, 31 Jan 2026 18:20:44 -0500 Subject: [PATCH] Initial commit --- .gitignore | 1 + skillshare/.skillshare-meta.json | 8 ++ skillshare/SKILL.md | 78 +++++++++++++ skillshare/references/TROUBLESHOOTING.md | 61 ++++++++++ skillshare/references/backup.md | 13 +++ skillshare/references/init.md | 35 ++++++ skillshare/references/install.md | 59 ++++++++++ skillshare/references/status.md | 62 +++++++++++ skillshare/references/sync.md | 49 ++++++++ skillshare/references/targets.md | 22 ++++ skillshare/scripts/run.sh | 135 +++++++++++++++++++++++ 11 files changed, 523 insertions(+) create mode 100644 .gitignore create mode 100644 skillshare/.skillshare-meta.json create mode 100644 skillshare/SKILL.md create mode 100644 skillshare/references/TROUBLESHOOTING.md create mode 100644 skillshare/references/backup.md create mode 100644 skillshare/references/init.md create mode 100644 skillshare/references/install.md create mode 100644 skillshare/references/status.md create mode 100644 skillshare/references/sync.md create mode 100644 skillshare/references/targets.md create mode 100755 skillshare/scripts/run.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/skillshare/.skillshare-meta.json b/skillshare/.skillshare-meta.json new file mode 100644 index 0000000..701ae58 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/skillshare/SKILL.md b/skillshare/SKILL.md new file mode 100644 index 0000000..bb0fc7f --- /dev/null +++ b/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 ` → `sync` | +| **Search** | `search `, `search --list`, `search --json` | +| **Install** | `install ` → `sync` | +| **Team repo** | `install --track` → `sync` | +| **Collect** | `collect ` → `sync` | +| **Update** | `update `, `update --all` → `sync` | +| **Remove** | `uninstall ` → `sync` | +| **Git sync** | `push -m "msg"`, `pull` | +| **Targets** | `target add

`, `target remove `, `target --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) | diff --git a/skillshare/references/TROUBLESHOOTING.md b/skillshare/references/TROUBLESHOOTING.md new file mode 100644 index 0000000..c6a3c8f --- /dev/null +++ b/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 ` 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 -- / # 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 +``` diff --git a/skillshare/references/backup.md b/skillshare/references/backup.md new file mode 100644 index 0000000..878f5be --- /dev/null +++ b/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//` diff --git a/skillshare/references/init.md b/skillshare/references/init.md new file mode 100644 index 0000000..d009a04 --- /dev/null +++ b/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 ` — 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 ` — Custom source (**only if user requests**) +- `--remote ` — 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 +``` diff --git a/skillshare/references/install.md b/skillshare/references/install.md new file mode 100644 index 0000000..946aac6 --- /dev/null +++ b/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 ` | 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 # Create SKILL.md template +skillshare new --dry-run # Preview +``` + +After create: Edit SKILL.md → `skillshare sync` diff --git a/skillshare/references/status.md b/skillshare/references/status.md new file mode 100644 index 0000000..dd4e4cc --- /dev/null +++ b/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 # Interactive (select to install) +skillshare search --list # List only, no install prompt +skillshare search --json # JSON output for scripting +skillshare search -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` diff --git a/skillshare/references/sync.md b/skillshare/references/sync.md new file mode 100644 index 0000000..bd5aa92 --- /dev/null +++ b/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` diff --git a/skillshare/references/targets.md b/skillshare/references/targets.md new file mode 100644 index 0000000..0881a78 --- /dev/null +++ b/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. diff --git a/skillshare/scripts/run.sh b/skillshare/scripts/run.sh new file mode 100755 index 0000000..dc918e8 --- /dev/null +++ b/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 "$@"