diff --git a/skills/skillshare/SKILL.md b/skills/skillshare/SKILL.md index f287db46d..0ad2110a0 100644 --- a/skills/skillshare/SKILL.md +++ b/skills/skillshare/SKILL.md @@ -1,166 +1,101 @@ --- name: skillshare -version: 0.6.0 -description: Manages and syncs skills across AI CLI tools (Claude, Cursor, Codex) from a single source of truth. Use when asked to "sync my skills", "pull skills", "show skillshare status", "list my skills", "install a skill", "install tracked repo", "update skills", or manage skill targets. +version: 0.7.0 +description: Syncs skills across AI CLI tools from a single source of truth. Use when asked to "sync skills", "pull skills", "show status", "list skills", "install skill", "initialize skillshare", or manage skill targets. argument-hint: "[command] [target] [--dry-run]" --- # Skillshare CLI -Syncs skills across multiple AI CLI tools from a single source of truth. +``` +Source: ~/.config/skillshare/skills ← Edit here (single source of truth) + ↓ sync +Targets: ~/.claude/skills, ~/.cursor/skills, ... ← Symlinked from source +``` -## Quick Start +## Quick Reference ```bash -skillshare status # See current state (always run first) -skillshare sync # Push skills to all targets -skillshare sync --dry-run # Preview changes before sync -skillshare pull claude # Bring new skills from target to source -skillshare list # Show installed skills +skillshare status # Always run first +skillshare sync # Push to all targets +skillshare sync --dry-run # Preview changes +skillshare pull claude # Import from target → source +skillshare list # Show skills and tracked repos ``` -## AI Behavior Guide +## Command Patterns -| User Intent | Commands | -|-------------|----------| -| "sync my skills" | `skillshare sync` | -| "sync but show me first" | `skillshare sync --dry-run` → `skillshare sync` | -| "pull from Claude" | `skillshare pull claude` → `skillshare sync` | -| "pull all" | `skillshare pull --all` → `skillshare sync` | -| "pull from remote" | `skillshare pull --remote` | -| "push to remote" | `skillshare push` | -| "show status" | `skillshare status` | -| "what skills do I have" | `skillshare list` | -| "install X skill" | `skillshare install ` → `skillshare sync` | -| "install team repo" | `skillshare install --track` → `skillshare sync` | -| "update skill" | `skillshare update ` → `skillshare sync` | -| "update all tracked repos" | `skillshare update --all` → `skillshare sync` | -| "remove X skill" | `skillshare uninstall ` → `skillshare sync` | -| "add cursor as target" | `skillshare target add cursor ~/.cursor/skills` | -| "something's broken" | `skillshare doctor` | -| "initialize skillshare" | See [Init Workflow](#init-workflow) | +| Intent | Command | +|--------|---------| +| Sync skills | `skillshare sync` | +| Preview first | `skillshare sync --dry-run` then `sync` | +| Pull from target | `skillshare pull ` then `sync` | +| Install skill | `skillshare install ` then `sync` | +| Install from repo (browse) | `skillshare install owner/repo` (discovery mode) | +| Install team repo | `skillshare install --track` then `sync` | +| Update skill/repo | `skillshare update ` then `sync` | +| Update all tracked | `skillshare update --all` then `sync` | +| Remove skill | `skillshare uninstall ` then `sync` | +| List skills | `skillshare list` or `list --verbose` | +| Cross-machine push | `skillshare push -m "message"` | +| Cross-machine pull | `skillshare pull --remote` | +| Backup/restore | `skillshare backup --list`, `restore ` | +| Add custom target | `skillshare target add ` | +| Change sync mode | `skillshare target --mode merge\|symlink` | +| Upgrade CLI/skill | `skillshare upgrade` | +| Diagnose issues | `skillshare doctor` | -## Init Workflow +## Init (Non-Interactive) -**CRITICAL:** AI cannot respond to CLI prompts. Use flags for non-interactive mode. +**CRITICAL:** Use flags — AI cannot respond to CLI prompts. -### Init Checklist +**Source path:** Always use default `~/.config/skillshare/skills`. Only use `--source` if user explicitly requests a different location. -Copy and track when initializing: -- [ ] Ask: "Do you have existing skills to copy?" → `--copy-from ` or `--no-copy` -- [ ] Ask: "Which CLI tools to sync?" → `--targets `, `--all-targets`, or `--no-targets` -- [ ] Ask: "Initialize git?" → `--git` or `--no-git` -- [ ] Run: `skillshare init [flags]` -- [ ] Verify: `skillshare status` - -### Quick Defaults - -If user just says "initialize skillshare": +**Step 1:** Check existing skills ```bash -skillshare init --no-copy --all-targets --git +ls ~/.claude/skills ~/.cursor/skills 2>/dev/null | head -10 ``` -### Examples +**Step 2:** Run init based on findings + +| Found | Command | +|-------|---------| +| Skills in one target | `skillshare init --copy-from --all-targets --git` | +| Skills in multiple | Ask user which to import | +| No existing skills | `skillshare init --no-copy --all-targets --git` | + +**Step 3:** `skillshare status` + +See [init.md](references/init.md) for all flags. + +## Team Edition ```bash -skillshare init --copy-from claude --targets "claude,cursor" --git -skillshare init --no-copy --all-targets --git # Fresh start -skillshare init --no-copy --no-targets --no-git # Minimal +skillshare install github.com/team/skills --track # Install as tracked repo +skillshare update _team-skills # Update later ``` -## Core Commands +Tracked repos: `_` prefix, nested paths use `__` (e.g., `_team__frontend__ui`). -| Command | Use Case | -|---------|----------| -| `status` | First command - see current state | -| `sync` | Push skills to all targets | -| `pull ` | Bring target's skills to source | -| `diff` | See differences between source and targets | -| `list` | Show installed skills and tracked repos | -| `install ` | Add skill from path or git repo | -| `install --track` | Install git repo as tracked repository | -| `update ` | Update skill or tracked repo | -| `update --all` | Update all tracked repos | -| `uninstall ` | Remove skill or tracked repo | -| `doctor` | Diagnose issues | +**Naming convention:** Use `{team}:{name}` in SKILL.md to avoid collisions. -## Team Edition (v0.6.0) +## Safety -Share skills with your team using tracked repositories: +- **NEVER** `rm -rf` on symlinked skills — deletes source +- Use `skillshare uninstall ` to safely remove -```bash -# Install team skills repo -skillshare install github.com/team/skills --track - -# Skills sync with _repo__ prefix -# _team-skills/frontend/ui → _team-skills__frontend__ui - -# Update later -skillshare update _team-skills # git pull -skillshare update --all # update all tracked repos -``` - -**Features:** -- Tracked repos start with `_` prefix (e.g., `_team-skills`) -- Nested paths use `__` separator (e.g., `team__frontend__ui`) -- Auto-pruning removes orphaned symlinks on sync -- Name collision detection warns about duplicate SKILL.md names -- Uninstall checks for uncommitted changes - -**Best Practice:** Use `{team}:{name}` format in SKILL.md to avoid name collisions: -```yaml -# In _acme-corp/frontend/ui/SKILL.md -name: acme:ui -``` - -## Nested Skills (Manual Organization) - -Organize skills in subdirectories — skillshare auto-flattens on sync: - -``` -Source Target -─────────────────────────────────── -my-skill/ → my-skill/ -work/api/ → work__api/ -personal/writing/ → personal__writing/ -``` - -A directory with `SKILL.md` is treated as a skill. - -## Symlink Safety - -**CRITICAL:** In `merge` mode, editing a skill in ANY target edits the source. - -- **NEVER** use `rm -rf` on symlinked skills - this deletes the source -- Use `skillshare target remove ` to safely unlink targets -- Use `skillshare uninstall ` to safely remove skills - -## Cross-Machine Workflow - -```bash -# Machine A: push changes -skillshare push -m "Add new skill" - -# Machine B: pull and sync -skillshare pull --remote -``` - -## Zero-Install Runner - -If skillshare is not installed, run directly via curl: +## Zero-Install ```bash curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/skills/skillshare/scripts/run.sh | sh -s -- status ``` -See [scripts/run.sh](scripts/run.sh) for the full runner script. - ## References -- [status.md](references/status.md) - status, diff, list, doctor -- [sync.md](references/sync.md) - sync, pull, push -- [install.md](references/install.md) - install, uninstall -- [targets.md](references/targets.md) - target management -- [backup.md](references/backup.md) - backup, restore -- [init.md](references/init.md) - init flags reference -- [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) - Common issues and recovery +- [init.md](references/init.md) - Init flags +- [sync.md](references/sync.md) - Sync, pull, push +- [install.md](references/install.md) - Install, update, uninstall +- [status.md](references/status.md) - Status, diff, list, doctor +- [targets.md](references/targets.md) - Target management +- [backup.md](references/backup.md) - Backup, restore +- [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) - Recovery diff --git a/skills/skillshare/references/init.md b/skills/skillshare/references/init.md index 36ffc7fdb..b44b51ee2 100644 --- a/skills/skillshare/references/init.md +++ b/skills/skillshare/references/init.md @@ -2,6 +2,13 @@ Initializes skillshare configuration. +## Key Concept + +**Source is always `~/.config/skillshare/skills`** — never a CLI directory like `.claude/skills`. + +- `--copy-from claude` = import skills FROM claude INTO source +- `--copy-from` does NOT change where source is located + ## Copy Source Flags (mutually exclusive) | Flag | Description | @@ -28,10 +35,12 @@ Initializes skillshare configuration. | Flag | Description | |------|-------------| -| `--source ` | Custom source directory | +| `--source ` | Custom source directory (**only if user explicitly requests**) | | `--remote ` | Set git remote (implies `--git`) | | `--dry-run` | Preview without making changes | +**AI Note:** Never use `--source` unless the user explicitly asks to change the source location. + ## Examples ```bash diff --git a/skills/skillshare/references/install.md b/skills/skillshare/references/install.md index 9dcf6adbf..d1f1b8c5c 100644 --- a/skills/skillshare/references/install.md +++ b/skills/skillshare/references/install.md @@ -1,13 +1,24 @@ -# Install & Uninstall Commands +# Install, Update & Uninstall ## install Adds a skill from various sources. ```bash -skillshare install github.com/user/repo # Discovery mode -skillshare install github.com/user/repo/path/skill # Direct path -skillshare install ~/Downloads/my-skill # Local path +# GitHub shorthand (auto-expands to github.com/...) +skillshare install owner/repo # Discovery mode +skillshare install owner/repo/path/to/skill # Direct path + +# Full URLs +skillshare install github.com/user/repo # Discovery mode +skillshare install github.com/user/repo/skill # Direct path +skillshare install git@github.com:user/repo.git # SSH + +# Local +skillshare install ~/Downloads/my-skill + +# Team repo (preserves .git for updates) +skillshare install github.com/team/skills --track ``` **Flags:** @@ -15,14 +26,24 @@ skillshare install ~/Downloads/my-skill # Local path | Flag | Description | |------|-------------| | `--name ` | Custom skill name | -| `--force` | Overwrite existing skill | -| `--update` | Update existing (git pull if possible, else reinstall) | +| `--force, -f` | Overwrite existing | +| `--update, -u` | Update existing (git pull or reinstall) | +| `--track, -t` | Install as tracked repo (Team Edition) | +| `--dry-run, -n` | Preview without installing | -**`--force` vs `--update`:** -- `--update`: Tries `git pull` first (for git repos without subdir), falls back to reinstall -- `--force`: Always delete and reinstall +After install: `skillshare sync` -After install, run `skillshare sync` to distribute to targets. +## update + +Updates skills or tracked repos. + +```bash +skillshare update my-skill # Update from stored source +skillshare update _team-repo # Git pull tracked repo +skillshare update --all # Update all tracked repos +``` + +After update: `skillshare sync` ## uninstall @@ -31,6 +52,7 @@ Removes a skill from source. ```bash skillshare uninstall my-skill # With confirmation skillshare uninstall my-skill --force # Skip confirmation +skillshare uninstall my-skill --dry-run ``` -After uninstall, run `skillshare sync` to update targets. +After uninstall: `skillshare sync` diff --git a/skills/skillshare/references/status.md b/skills/skillshare/references/status.md index 6254e9f1c..c2172a254 100644 --- a/skills/skillshare/references/status.md +++ b/skills/skillshare/references/status.md @@ -42,3 +42,17 @@ 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`