mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
docs: simplify skillshare skill docs and bump to v0.7.0
- Condense SKILL.md with cleaner command pattern table - Add GitHub shorthand (owner/repo) format examples - Document upgrade command in status.md - Clarify source path concept in init.md - Reorganize install.md with update command section
This commit is contained in:
+66
-131
@@ -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 <source>` → `skillshare sync` |
|
||||
| "install team repo" | `skillshare install <git-url> --track` → `skillshare sync` |
|
||||
| "update skill" | `skillshare update <name>` → `skillshare sync` |
|
||||
| "update all tracked repos" | `skillshare update --all` → `skillshare sync` |
|
||||
| "remove X skill" | `skillshare uninstall <name>` → `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 <name>` then `sync` |
|
||||
| Install skill | `skillshare install <source>` then `sync` |
|
||||
| Install from repo (browse) | `skillshare install owner/repo` (discovery mode) |
|
||||
| Install team repo | `skillshare install <git-url> --track` then `sync` |
|
||||
| Update skill/repo | `skillshare update <name>` then `sync` |
|
||||
| Update all tracked | `skillshare update --all` then `sync` |
|
||||
| Remove skill | `skillshare uninstall <name>` 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 <target>` |
|
||||
| Add custom target | `skillshare target add <name> <path>` |
|
||||
| Change sync mode | `skillshare target <name> --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 <name>` or `--no-copy`
|
||||
- [ ] Ask: "Which CLI tools to sync?" → `--targets <list>`, `--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 <name> --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 <target>` | Bring target's skills to source |
|
||||
| `diff` | See differences between source and targets |
|
||||
| `list` | Show installed skills and tracked repos |
|
||||
| `install <source>` | Add skill from path or git repo |
|
||||
| `install --track` | Install git repo as tracked repository |
|
||||
| `update <name>` | Update skill or tracked repo |
|
||||
| `update --all` | Update all tracked repos |
|
||||
| `uninstall <name>` | 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 <name>` 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 <name>` to safely unlink targets
|
||||
- Use `skillshare uninstall <name>` 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
|
||||
|
||||
@@ -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 <path>` | Custom source directory |
|
||||
| `--source <path>` | Custom source directory (**only if user explicitly requests**) |
|
||||
| `--remote <url>` | 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
|
||||
|
||||
@@ -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 <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`
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user