skillshare
Sync skills to all your AI CLI tools with one command
Supports Amp, Claude Code, Codex CLI, Crush, Cursor, Gemini CLI, GitHub Copilot, Goose, Letta, Antigravity, OpenCode
Install • Quick Start • Commands • Reference • FAQ • Common Issues
Why skillshare?
The problem: You create a skill in Claude, but need it in Cursor, Codex, and Gemini too. Manually copying? Tedious. What if you update it? Copy again.
The solution: One source of truth. Create once, sync everywhere.
skillshare pull claude && skillshare sync # Pull from Claude → sync to all
| What makes it different | |
|---|---|
| 🔄 Bidirectional sync | pull from any target, sync to all |
| 🌐 Cross-machine sync | push / pull --remote via git |
| 💾 Backup & restore | Automatic before sync, restore anytime |
| 🔍 Diagnostics | doctor checks git, broken links, duplicates |
| 🤖 AI-native | Built-in skill lets your AI manage everything |
AI-Native Execution
The built-in skillshare skill enables your AI CLI to manage skills directly. Just download the skill folder into your AI CLI's skills directory — the binary is auto-downloaded on first use.
┌─────────────────────────────────────────────────────────────┐
│ User: "sync my skills to all targets" │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ AI reads skillshare skill │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ skillshare sync │
│ ✓ Synced 5 skills to claude, codex, cursor │
└─────────────────────────────────────────────────────────────┘
Tip
Once installed, just say:
- "Show my skillshare status"
- "Sync my skills to all targets"
- "Pull skills from Claude and sync everywhere"
- "Install the pdf skill from anthropics/skills"
Installation
Quick Install
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
Installs to /usr/local/bin/. Works on macOS and Linux.
Homebrew (macOS)
brew install runkids/tap/skillshare
Manual install
macOS
# Apple Silicon (M1/M2/M3/M4)
curl -sL https://github.com/runkids/skillshare/releases/latest/download/skillshare_darwin_arm64.tar.gz | tar xz
sudo mv skillshare /usr/local/bin/
# Intel
curl -sL https://github.com/runkids/skillshare/releases/latest/download/skillshare_darwin_amd64.tar.gz | tar xz
sudo mv skillshare /usr/local/bin/
Linux
# x86_64
curl -sL https://github.com/runkids/skillshare/releases/latest/download/skillshare_linux_amd64.tar.gz | tar xz
sudo mv skillshare /usr/local/bin/
# ARM64
curl -sL https://github.com/runkids/skillshare/releases/latest/download/skillshare_linux_arm64.tar.gz | tar xz
sudo mv skillshare /usr/local/bin/
Windows
Download from Releases and add to PATH.
Uninstall
brew uninstall skillshare # Homebrew
sudo rm /usr/local/bin/skillshare # Manual install
rm -rf ~/.config/skillshare # Config & data (optional)
Quick Start
skillshare init --dry-run # Preview setup
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/ │
│ my-skill/ another-skill/ shared-util/ │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Claude │ │ Codex │ │ Gemini │
│ skills/ │ │ skills/ │ │ skills/ │
└───────────┘ └───────────┘ └───────────┘
Commands
| Command | Description |
|---|---|
init |
Initialize skillshare, detect CLIs, setup git |
install |
Install a skill from local path or git repo |
uninstall |
Remove a skill from source directory |
list |
List all installed skills |
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 |
pull --remote |
Pull from git remote and sync to all targets |
push |
Commit and push skills to git remote |
backup |
Manually backup targets |
restore |
Restore from backup |
doctor |
Diagnose configuration issues |
upgrade |
Upgrade CLI and built-in skillshare skill |
Target Management
| Command | Description |
|---|---|
target list |
List all configured targets |
target <name> |
Show target info (path, mode, status) |
target <name> --mode <mode> |
Change sync mode (merge/symlink) |
target add <name> <path> |
Add custom target |
target remove <name> |
Safely unlink target (backs up first) |
Reference
Jump to a section:
- Target Management
- Install Skills
- Uninstall Skills
- List Skills
- Upgrade
- Dry Run
- Sync Modes
- Backup & Restore
- Cross-Machine Sync
- Configuration
- FAQ
- Common Issues
Target Management
Add, remove, or configure targets for any AI CLI tool.
skillshare target list # List all targets
skillshare target claude # Show target info
skillshare target claude --mode merge # Change sync mode
skillshare target add myapp ~/.myapp/skills # Add custom target
skillshare target remove myapp # Safely unlink (backs up first)
Adding Custom Targets
Support any tool with a skills directory:
skillshare target add windsurf ~/.windsurf/skills
skillshare target add aider ~/.aider/skills
skillshare sync
Removing Targets Safely
target remove is safe — it backs up first, then replaces symlinks with copies:
skillshare target remove claude # Backup → unlink → copy back
skillshare target remove --all # Remove all targets
Warning
Never use
rm -rfon a symlinked target — it deletes your source files!
Install Skills
Install skills from local paths or git repositories directly into your source directory.
GitHub Shorthand
Use owner/repo shorthand for quick installs (automatically expands to github.com/owner/repo):
skillshare install anthropics/skills # Discovery mode
skillshare install anthropics/skills/skills/pdf # Direct install
skillshare install ComposioHQ/awesome-claude-skills # Another repo
From Git Repository (Discovery Mode)
When installing from a git repo without a specific path, skillshare discovers all skills and lets you choose:
$ skillshare install anthropics/skills
Discovering skills
─────────────────────────────────────────
→ Source: github.com/anthropics/skills
→ Cloning repository...
✓ Found 17 skill(s)
? Select skills to install:
[Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
> [ ] algorithmic-art (skills/algorithmic-art)
[ ] brand-guidelines (skills/brand-guidelines)
[ ] canvas-design (skills/canvas-design)
[ ] doc-coauthoring (skills/doc-coauthoring)
[ ] frontend-design (skills/frontend-design)
[ ] mcp-builder (skills/mcp-builder)
[ ] pdf (skills/pdf)
...
Direct Install (Specific Path)
Install a specific skill directly by providing the full path:
# GitHub shorthand with subdirectory
skillshare install google-gemini/gemini-cli/packages/core/src/skills/builtin/skill-creator
# From local path
skillshare install ~/Downloads/my-skill
# From SSH git URL
skillshare install git@github.com:user/repo.git
Options
| Option | Description |
|---|---|
--name <name> |
Override the skill name (direct install only) |
--force, -f |
Overwrite if skill already exists |
--update, -u |
Update existing (git pull if possible, else reinstall) |
--dry-run, -n |
Preview discovered skills without installing |
Examples
# Preview available skills in a repo
skillshare install github.com/ComposioHQ/awesome-claude-skills --dry-run
# Install specific skill with custom name
skillshare install github.com/google-gemini/gemini-cli/packages/core/src/skills/builtin/skill-creator --name my-skill-creator
# Force overwrite existing
skillshare install ~/my-skill --force
# Update existing git-based installation
skillshare install github.com/user/skill-repo --update
After installing, run skillshare sync to distribute the skill to all targets.
Uninstall Skills
Remove a skill from the source directory.
skillshare uninstall my-skill # Prompts for confirmation
skillshare uninstall my-skill --force # Skip confirmation
skillshare uninstall my-skill --dry-run # Preview without removing
After uninstalling, run skillshare sync to update all targets.
List Skills
View all installed skills and their sources.
skillshare list # List all skills
skillshare list --verbose # Show detailed info (source, type, install date)
Example output:
Installed skills
--------------------------------------------------
my-skill (local)
skill-creator github.com/google-gemini/gemini-cli/...
composio-skills github.com/ComposioHQ/awesome-claude-skills
Upgrade
Upgrade the CLI binary and built-in skillshare skill to the latest version.
skillshare upgrade # Upgrade CLI + skill
skillshare upgrade --skill # Upgrade skill only
skillshare upgrade --cli # Upgrade CLI only
skillshare upgrade --force # Skip confirmation
skillshare upgrade --dry-run # Preview without upgrading
After upgrading the skill, run skillshare sync to distribute to all targets.
Dry Run
Preview changes without modifying files. Supported commands:
skillshare init --dry-run # Preview init setup
skillshare install <source> --dry-run # Preview install
skillshare uninstall <name> --dry-run # Preview uninstall
skillshare sync --dry-run # Preview sync changes
skillshare sync -n # Short flag for sync
skillshare pull --dry-run # Preview pull changes
skillshare pull -n # Short flag for pull
skillshare pull claude -n # Preview pull for one target
skillshare pull --all -n # Preview pull for all targets
skillshare backup --dry-run # Preview backups
skillshare backup -n # Short flag for backup
skillshare backup --cleanup -n # Preview cleanup
skillshare backup --list # List backups (read-only)
skillshare restore claude -n # Preview restore from latest
skillshare restore claude --from 2026-01-14_21-22-18 -n # Preview restore from timestamp
skillshare target remove claude -n # Preview unlink
skillshare target remove --all -n # Preview unlink all
skillshare upgrade -n # Preview upgrade
Sync Modes
| 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. |
Change mode:
skillshare target claude --mode merge
skillshare sync
Warning
Symlink Safety — Deleting through a symlinked target deletes the source:
rm -rf ~/.codex/skills/my-skill # ❌ Deletes from SOURCE! skillshare target remove codex # ✅ Safe way to unlink
Backup & Restore
Backups are created automatically before sync and target remove.
Location: ~/.config/skillshare/backups/<timestamp>/
skillshare backup # Manual backup all targets
skillshare backup claude # Backup specific target
skillshare backup --list # List all backups
skillshare backup --cleanup # Remove old backups
skillshare restore claude # Restore from latest backup
skillshare restore claude --from 2026-01-14_21-22-18 # Specific backup
Note: In
symlinkmode, backups are skipped (no local data to backup).
Cross-Machine Sync
Sync your skills across multiple computers using git.
┌─────────────────┐ ┌─────────────────┐
│ Machine A │ │ Machine B │
│ │ skillshare push │ │
│ Claude/Codex │ ─────────────────► │ Claude/Cursor │
│ ↕ symlink │ │ ↕ symlink │
│ source/skills │ ┌───────────┐ │ source/skills │
│ │ │ │ GitHub │ │ │ │
│ └────────┼──►│ Remote │◄─────┼────────┘ │
│ │ └───────────┘ │ │
│ │ ◄─────────────────── │ │
│ │ skillshare pull │ │
│ │ --remote │ │
└─────────────────┘ └─────────────────┘
Setup
# New setup with remote
skillshare init --remote git@github.com:you/my-skills.git
# Or add remote to existing setup
cd ~/.config/skillshare/skills
git remote add origin git@github.com:you/my-skills.git
Daily Workflow
# Push changes to remote (git add + commit + push)
skillshare push
skillshare push -m "Add new skill" # Custom message
# Pull from remote and sync to all targets
skillshare pull --remote
Second Machine Setup
# Clone your skills repo
git clone git@github.com:you/my-skills.git ~/.config/skillshare/skills
# Initialize skillshare with existing source
skillshare init --source ~/.config/skillshare/skills
# Sync to all local targets
skillshare sync
Conflict Handling
pushfails if remote is ahead → runpull --remotefirstpull --remoterefuses if local has uncommitted changes → runpushfirst
Configuration
Config file: ~/.config/skillshare/config.yaml
source: ~/.config/skillshare/skills
mode: merge
targets:
claude:
path: ~/.claude/skills
codex:
path: ~/.codex/skills
mode: symlink # Override default mode
cursor:
path: ~/.cursor/skills
ignore:
- "**/.DS_Store"
- "**/.git/**"
FAQ
Isn't this just ln -s?
Yes, at its core. But skillshare handles multi-target detection, backup/restore, merge mode, cross-device sync, and broken symlink recovery — so you don't have to.
Can I sync skills to a custom or uncommon tool?
Yes. Use skillshare target add <name> <path> with the tool's skills directory.
How do I sync across multiple machines?
See Cross-Machine Sync section.
What happens if I modify a skill in the target directory?
Since targets are symlinks, changes are made directly to the source. All targets see the change immediately.
How do I keep a CLI-specific skill?
Use merge mode. Local skills in the target won't be overwritten.
What if I accidentally delete a skill through a symlink?
If you have git initialized (recommended), recover with:
cd ~/.config/skillshare/skills
git checkout -- deleted-skill/
How does target remove work? Is it safe?
Yes, it's safe. Here's how it works:
┌─────────────────────────────────────────────────────────┐
│ skillshare target remove claude │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────┐
│ 1. Backup target │
│ (backups/<ts>/) │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 2. Detect mode │
└─────────────────────┘
│ │
symlink mode merge mode
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ 3a. Remove symlink │ │ 3b. For each skill: │
│ ~/.claude/skills │ │ Check if symlink │
│ ↓ │ │ points to source │
│ 4a. Copy source │ │ ↓ │
│ contents back │ │ 4b. If yes: │
└───────────────────────┘ │ - Remove symlink │
│ - Copy back file │
└───────────────────────┘
│
▼
┌─────────────────────┐
│ 5. Remove from │
│ config.yaml │
└─────────────────────┘
- Symlink mode: Removes symlink, copies source contents back to target
- Merge mode: Only removes symlinks pointing to source, preserves local-only skills
This is why skillshare target remove is safe, while rm -rf ~/.claude/skills would delete your source files.
Common Issues
- Seeing
config not found: run 'skillshare init' first: runskillshare init(add--sourceif you want a custom path). - Integration tests cannot find the binary: run
go build -o bin/skillshare ./cmd/skillshareor setSKILLSHARE_TEST_BINARY. - Deleting a symlinked target removed source files: use
skillshare target remove <name>to unlink, then recover via git if needed. - Target directory already exists with files: run
skillshare backupbeforeskillshare syncto migrate safely. - Target path does not end with
skills: verify the path and prefer.../skillsas the suffix.
Contributing
git clone https://github.com/runkids/skillshare.git
cd skillshare
go build -o bin/skillshare ./cmd/skillshare
go test ./...
Open an issue for bugs or feature requests.
License
MIT

