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:
Willie Hung
2026-01-20 21:39:20 +08:00
parent 64669e62ba
commit 8a5cd8cea9
4 changed files with 123 additions and 143 deletions
+66 -131
View File
@@ -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
+10 -1
View File
@@ -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
+33 -11
View File
@@ -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`
+14
View File
@@ -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`