diff --git a/.github/assets/demo.gif b/.github/assets/demo.gif new file mode 100644 index 000000000..956013669 Binary files /dev/null and b/.github/assets/demo.gif differ diff --git a/README.md b/README.md index 5dafb1aec..7381362d7 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,40 @@
- Share skills across AI CLI tools (Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode).
+ Sync skills to all your AI CLI tools with one command
+ Supports Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode
+
+
+ Install • + Quick Start • + Commands • + FAQ +
+ +## Installation + +```bash +brew install runkids/tap/skillshare +``` + +> Other methods: [Detailed Installation](#detailed-installation) + +## Quick Start + +```bash +skillshare init # Auto-detects installed CLIs, sets up git +skillshare sync # Syncs skills to all targets +``` + +Done! Your skills are now synced across all AI CLI tools. + +## How It Works + ``` ┌─────────────────────────────────────────────────────────────┐ │ ~/.config/skillshare/skills/ │ @@ -29,40 +60,25 @@ └───────────┘ └───────────┘ └───────────┘ ``` -## Table of Contents +## Commands -- [Why skillshare?](#why-skillshare) -- [Installation](#installation) -- [Quick Start](#quick-start) -- [Usage](#usage) -- [Sync Modes](#sync-modes) -- [Backup & Restore](#backup--restore) -- [Configuration](#configuration) -- [Use Cases](#use-cases) -- [Sync Across Machines](#sync-across-machines) -- [FAQ](#faq) -- [Contributing](#contributing) -- [License](#license) +| Command | Description | +|---------|-------------| +| `init` | Initialize skillshare, detect CLIs, setup git | +| `sync` | Sync skills to all targets | +| `status` | Show source, targets, and sync state | +| `diff` | Show differences between source and targets | +| `pull` | Pull skills from target back to source | +| `backup` | Manually backup targets | +| `restore` | Restore from backup | +| `doctor` | Diagnose configuration issues | +| `target` | Manage targets (add/remove/list/mode) | -## Why skillshare? +--- -Each AI CLI tool has its own skills directory, and keeping them in sync manually is tedious. +# Detailed Documentation -| Manual Management | skillshare | -|-------------------|------------| -| Copy to each CLI directory | Set up once, auto-sync | -| Update requires multiple copies | Change once, update everywhere | -| Easy to miss or have inconsistent versions | Always in sync | -| No change tracking | Git version control support | -| Skills lost when CLI is removed | Safe backup mechanism | - -## Installation - -### Homebrew (Recommended) - -```bash -brew install runkids/tap/skillshare -``` +## Detailed Installation ### macOS @@ -92,268 +108,54 @@ sudo mv skillshare /usr/local/bin/ Download from [Releases](https://github.com/runkids/skillshare/releases) and add to PATH. -### Verify Installation - -```bash -skillshare version -``` - ### Uninstall ```bash -# Homebrew -brew uninstall skillshare - -# Manual (curl install) -sudo rm /usr/local/bin/skillshare - -# Config and data (optional) -rm -rf ~/.config/skillshare -``` - -## Quick Start - -```bash -# 1. Initialize (auto-detects CLIs, prompts for git setup) -skillshare init - -# 2. Check detected targets -skillshare status - -# 3. Sync skills to all targets -skillshare sync - -# 4. (Optional) Push to remote for backup -cd ~/.config/skillshare/skills -git remote add origin git@github.com:you/my-skills.git -git push -u origin main -``` - -## Usage - -### Initialize - -```bash -# Interactive mode - choose source from existing skills directories -skillshare init - -# Or specify custom source -skillshare init --source ~/my-skills -``` - -This will: -- Detect installed CLI tools -- Optionally copy skills from existing directories -- Initialize git for version control (recommended for recovery) -- Create config at `~/.config/skillshare/config.yaml` - -### Sync - -```bash -# Preview what will happen -skillshare sync --dry-run - -# Actually sync -skillshare sync - -# Force sync (override conflicts) -skillshare sync --force -``` - -### Status - -```bash -skillshare status -``` - -Shows source directory, skill count, and each target's sync state. - -### Diff - -```bash -# Show differences for all targets -skillshare diff - -# Show differences for specific target -skillshare diff claude -``` - -### Pull - -```bash -# Pull local skills from specific target to source -skillshare pull claude - -# Pull from all targets -skillshare pull --all - -# Preview what will be pulled -skillshare pull --dry-run - -# Force overwrite existing skills in source -skillshare pull --force -``` - -Copies skills created in target directories back to source. Useful when you create skills directly in a CLI's skills directory (e.g., `~/.claude/skills/`) and want to share them with other CLIs. - -**Typical workflow:** -1. Create a skill in `~/.claude/skills/my-new-skill/` -2. Run `skillshare pull claude` to copy it to source -3. Run `skillshare sync` to distribute to all targets - -### Doctor - -```bash -skillshare doctor -``` - -Diagnoses config, source directory, symlink support, and target health. - -### Manage Targets - -```bash -# List all targets -skillshare target list - -# Show target info -skillshare target claude - -# Change target sync mode -skillshare target claude --mode merge -skillshare target claude --mode symlink - -# Add custom target -skillshare target add myapp ~/.myapp/skills - -# Unlink target (restore skills and remove from config) -skillshare target remove myapp - -# Unlink all targets -skillshare target remove --all -``` - -#### Target Validation - -When adding a target, skillshare validates: - -| Check | Behavior | -|-------|----------| -| Name format | Must start with a letter, only letters/numbers/underscores/hyphens | -| Reserved names | Cannot use `add`, `remove`, `list`, `help`, `all` | -| Path ending | Warns if path doesn't end with `skills` | -| Directory exists | Warns if target or parent directory doesn't exist | - -```bash -# These will be rejected: -skillshare target add 123test ~/path # Name starts with number -skillshare target add add ~/path # Reserved name - -# This will show a warning and ask for confirmation: -skillshare target add myapp ~/Documents # Path doesn't look like skills dir +brew uninstall skillshare # Homebrew +sudo rm /usr/local/bin/skillshare # Manual install +rm -rf ~/.config/skillshare # Config & data (optional) ``` ## Sync Modes -| Mode | Behavior | Backup Value | -|------|----------|--------------| -| `symlink` | Entire directory becomes a symlink to source. All targets share exactly the same skills. | Low (all synced) | -| `merge` (recommended) | Each skill is symlinked individually. Local skills in target are preserved. | High (local skills) | +| Mode | Behavior | When to Use | +|------|----------|-------------| +| `merge` | Each skill symlinked individually. Local skills preserved. | **Recommended.** Safe, flexible. | +| `symlink` | Entire directory becomes symlink. All targets identical. | When you want exact copies everywhere. | -**Recommendation**: Use `merge` mode for safety. It preserves local skills and is safer to manage. - -Change mode per target: +Change mode: ```bash skillshare target claude --mode merge skillshare sync ``` -### ⚠️ Important: Symlink Safety +### ⚠️ Symlink Safety -When using symlinks, **deleting files through a target directory deletes the source**: +Deleting through a symlinked target **deletes the source**: ```bash -# DANGER: This deletes your SOURCE skills! -rm -rf ~/.codex/skills/* # ❌ Deletes source! -rm -rf ~/.codex/skills/my-skill # ❌ Deletes from source! - -# SAFE: Use skillshare commands instead -skillshare target remove codex # ✅ Safely unlinks +rm -rf ~/.codex/skills/my-skill # ❌ Deletes from SOURCE! +skillshare target remove codex # ✅ Safe way to unlink ``` -**Safe practices:** -- Always use `skillshare target remove` to unlink targets -- Never manually delete files inside symlinked directories -- Keep your source in a git repo for recovery -- Use `merge` mode if you're unsure - ## Backup & Restore -### Automatic Backups +Backups are created **automatically** before `sync` and `target remove`. -Backups are created automatically before: -- `skillshare sync` - backs up targets before syncing -- `skillshare target remove` - backs up before unlinking - -Backup location: `~/.config/skillshare/backups/