https://github.com/runkids/skillshare
📚 Sync skills to all your AI CLI tools with one command for Claude, Codex, Cursor, Antigravity & more
https://github.com/runkids/skillshare
ai amp antigravity claude-code cli codex cross-machine-sync cursor dotfiles opencode skills skills-management skillshare team-management
Last synced: about 10 hours ago
JSON representation
📚 Sync skills to all your AI CLI tools with one command for Claude, Codex, Cursor, Antigravity & more
- Host: GitHub
- URL: https://github.com/runkids/skillshare
- Owner: runkids
- License: mit
- Created: 2026-01-14T10:07:46.000Z (7 days ago)
- Default Branch: main
- Last Pushed: 2026-01-19T18:39:02.000Z (1 day ago)
- Last Synced: 2026-01-19T22:54:59.503Z (1 day ago)
- Topics: ai, amp, antigravity, claude-code, cli, codex, cross-machine-sync, cursor, dotfiles, opencode, skills, skills-management, skillshare, team-management
- Language: Go
- Homepage:
- Size: 21.8 MB
- Stars: 166
- Watchers: 3
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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.
```bash
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](https://github.com/runkids/skillshare/tree/main/skills/skillshare) enables your AI CLI to manage skills directly — **no manual installation required**.
```text
┌─────────────────────────────────────────────────────────────┐
│ User: "sync my skills to all targets" │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ AI reads skillshare skill │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ skillshare sync │
│ ✓ Synced 5 skills to claude, codex, cursor │
└─────────────────────────────────────────────────────────────┘
```
> [!TIP]
> The skill automatically downloads the binary on first use — 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
```bash
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
```
Installs to `/usr/local/bin/`. Works on macOS and Linux.
### Homebrew (macOS)
```bash
brew install runkids/tap/skillshare
```
### Manual install
#### macOS
```bash
# 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
```bash
# 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](https://github.com/runkids/skillshare/releases) and add to PATH.
### Uninstall
```bash
brew uninstall skillshare # Homebrew
sudo rm /usr/local/bin/skillshare # Manual install
rm -rf ~/.config/skillshare # Config & data (optional)
```
## Quick Start
```bash
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 |
| `update` | Update built-in skillshare skill from GitHub |
### Target Management
| Command | Description |
|---------|-------------|
| `target list` | List all configured targets |
| `target ` | Show target info (path, mode, status) |
| `target --mode ` | Change sync mode (merge/symlink) |
| `target add ` | Add custom target |
| `target remove ` | Safely unlink target (backs up first) |
---
## Reference
Jump to a section:
- [Target Management](#target-management-1)
- [Install Skills](#install-skills)
- [Uninstall Skills](#uninstall-skills)
- [List Skills](#list-skills)
- [Update Built-in Skill](#update-built-in-skill)
- [Dry Run](#dry-run)
- [Sync Modes](#sync-modes)
- [Backup & Restore](#backup--restore)
- [Cross-Machine Sync](#cross-machine-sync)
- [Configuration](#configuration)
- [FAQ](#faq)
- [Common Issues](#common-issues)
## Target Management
Add, remove, or configure targets for any AI CLI tool.
```bash
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:
```bash
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:
```bash
skillshare target remove claude # Backup → unlink → copy back
skillshare target remove --all # Remove all targets
```
> [!WARNING]
> Never use `rm -rf` on 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`):
```bash
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:
```bash
$ 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, to all, 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:
```bash
# 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 ` | Override the skill name (direct install only) |
| `--force, -f` | Overwrite if skill already exists |
| `--update, -u` | Update existing installation (git pull) |
| `--dry-run, -n` | Preview discovered skills without installing |
### Examples
```bash
# 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.
```bash
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.
```bash
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
```
## Update Built-in Skill
> **Note:** Available since v0.3.1
Update the built-in `skillshare` skill to the latest version from GitHub. This skill enables AI-driven management of your skills.
```bash
skillshare update # Update skillshare skill
skillshare update --force # Skip confirmation
skillshare update --dry-run # Preview without updating
```
The skill is downloaded from the [skillshare repository](https://github.com/runkids/skillshare/tree/main/skills/skillshare) and includes AI behavior guides, command references, and troubleshooting tips.
After updating, run `skillshare sync` to distribute to all targets.
## Dry Run
Preview changes without modifying files. Supported commands:
```bash
skillshare init --dry-run # Preview init setup
skillshare install --dry-run # Preview install
skillshare uninstall --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 update -n # Preview skill update
```
## 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:
```bash
skillshare target claude --mode merge
skillshare sync
```
> [!WARNING]
> **Symlink Safety** — Deleting through a symlinked target **deletes the source**:
> ```bash
> 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//`
```bash
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 `symlink` mode, 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
```bash
# 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
```bash
# 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
```bash
# 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
- `push` fails if remote is ahead → run `pull --remote` first
- `pull --remote` refuses if local has uncommitted changes → run `push` first
## Configuration
Config file: `~/.config/skillshare/config.yaml`
```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 ` with the tool's skills directory.
**How do I sync across multiple machines?**
See [Cross-Machine Sync](#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:
```bash
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//) │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 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`: run `skillshare init` (add `--source` if you want a custom path).
- Integration tests cannot find the binary: run `go build -o bin/skillshare ./cmd/skillshare` or set `SKILLSHARE_TEST_BINARY`.
- Deleting a symlinked target removed source files: use `skillshare target remove ` to unlink, then recover via git if needed.
- Target directory already exists with files: run `skillshare backup` before `skillshare sync` to migrate safely.
- Target path does not end with `skills`: verify the path and prefer `.../skills` as the suffix.
## Contributing
```bash
git clone https://github.com/runkids/skillshare.git
cd skillshare
go build -o bin/skillshare ./cmd/skillshare
go test ./...
```
[Open an issue](https://github.com/runkids/skillshare/issues) for bugs or feature requests.
## License
MIT