## New Features
- Tracked repositories: `install --track` to clone team skill repos
- Nested skills: organize in folders, auto-flatten on sync (work/api → work__api)
- Name collision detection: warns when multiple skills share same SKILL.md name
- Auto-pruning: orphaned symlinks cleaned on sync
- Custom naming: `--name` flag for tracked repos
## Changes
- Require target path to exist when adding targets
- Add sync reminder after adding target
- Improve pruning messages (broken vs orphan symlinks)
- Add `{team}:{name}` naming convention recommendation
## Files
- New: update.go, gitignore.go, frontmatter.go
- Updated: sync.go, install.go, uninstall.go, validate.go
- Docs: README.md, SKILL.md
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 • Team Edition • Reference • FAQ • Common Issues
Note
What's New in 0.6.0 — Team Edition
- Tracked Repositories:
install --trackto clone team skill repos,updateto keep them current- Nested Skills: Organize skills in folders (
work/api/→work__api/)- Auto-Pruning: Orphaned symlinks are automatically cleaned on sync
- Collision Detection: Warns when multiple skills share the same name
- Learn more →
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
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 │ │ OpenCode │
│ skills/ │ │ skills/ │ │ skills/ │
└───────────┘ └───────────┘ └───────────┘
Nested paths like
work/api/are flattened towork__api/in targets. See Nested Skills.
Commands
| Command | Description |
|---|---|
init |
Initialize skillshare, detect CLIs, setup git |
install |
Install a skill from local path or git repo |
install --track |
Install a git repo as tracked repository (Team Edition) |
uninstall |
Remove a skill or tracked repo from source |
list |
List all installed skills and tracked repos |
sync |
Sync skills to all targets (with auto-pruning) |
status |
Show source, targets, tracked repos, 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 |
update |
Update a skill or tracked repository |
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) |
Team Edition
Share skills across your team with tracked repositories. Clone once, update with git pull, sync everywhere.
Why Team Edition?
| Feature | Before | After |
|---|---|---|
| Share skills | Manual copy | install --track + sync |
| Update skills | Re-download | update <name> |
| Nested organization | Not supported | team/frontend/ui → team__frontend__ui |
| Clean up | Manual | Auto-pruning on sync |
Quick Start
# Install a team skills repo
skillshare install github.com/team/shared-skills --track
# Sync to all targets
skillshare sync
# Later, update the repo
skillshare update _shared-skills
skillshare sync
How It Works
Source Directory Target Directory
─────────────────────────────────────────────────────────────
skills/
├── my-local-skill/ my-local-skill/
├── personal/
│ └── writing/
│ └── email/ personal__writing__email/
└── _team-repo/ ─────►
├── frontend/
│ └── ui/ _team-repo__frontend__ui/
└── backend/
└── api/ _team-repo__backend__api/
Key concepts:
- Tracked repos start with
_(e.g.,_team-repo) - Nested paths use
__separator (e.g.,a/b/c→a__b__c) - Auto-pruning removes orphaned symlinks on sync
Commands
# Install as tracked repository (preserves .git)
skillshare install github.com/team/skills --track
skillshare install github.com/team/skills --track --name custom-name
# Update tracked repos
skillshare update _team-repo # Update specific repo
skillshare update --all # Update all tracked repos
# View tracked repos
skillshare list # Shows skills + tracked repos
skillshare status # Shows repo status (up-to-date/has changes)
# Uninstall tracked repo
skillshare uninstall _team-repo # Checks for uncommitted changes
skillshare uninstall _team-repo -f # Force (ignore uncommitted changes)
Nested Skills (Manual Organization)
Organize skills in subdirectories for better categorization. Skillshare automatically flattens them during sync:
Source (your organization) Target (flattened for CLI)
─────────────────────────────────────────────────────────────
skills/
├── my-skill/ → my-skill/
├── personal/
│ └── writing/
│ └── email/ → personal__writing__email/
└── work/
├── frontend/
│ └── react/ → work__frontend__react/
└── backend/
└── api/ → work__backend__api/
How it works:
- A directory with
SKILL.mdis treated as a skill - Nested paths use
__(double underscore) as separator - Original folder structure is preserved in source
- CLI tools see flat names (required by most AI CLIs)
# Create nested structure manually
mkdir -p ~/.config/skillshare/skills/personal/writing/email
cat > ~/.config/skillshare/skills/personal/writing/email/SKILL.md << 'EOF'
---
name: email-helper
description: Help write professional emails
---
# Email Helper
EOF
# Sync - creates personal__writing__email/ symlink in all targets
skillshare sync
Note
This works for both personal organization and tracked repos (
_repo/path→_repo__path).
Name Collision Detection
If multiple skills have the same name in their SKILL.md, sync will warn you:
Name conflicts detected
─────────────────────────────────────────
! Skill name 'deploy' is defined in multiple places:
→ - work/frontend/deploy
→ - work/backend/deploy
→ CLI tools may not distinguish between them.
→ Suggestion: Rename one in SKILL.md (e.g., 'frontend-deploy')
Why this matters: CLI tools identify skills by the name field in SKILL.md, not the directory name. Duplicate names cause unpredictable behavior.
Tip
Best Practice for Team Repos: Use
{team}:{name}format in SKILL.md to avoid collisions:# In _acme-corp/frontend/ui/SKILL.md name: acme:uiThis ensures skills from different teams never conflict.
Auto-Pruning
When you delete a skill from source, sync automatically removes it from targets:
rm -rf ~/.config/skillshare/skills/_team/old-skill
skillshare sync
# Output: ✓ target: merged (5 linked, 0 local, 0 updated, 1 pruned)
Safety rules:
- Only removes symlinks pointing to source
- Only removes directories with
_prefix or__in name - Warns about unknown directories (never auto-deletes)
Reference
Jump to a section:
- Target Management
- Install Skills
- Uninstall Skills
- List Skills
- Update 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) |
--track, -t |
Install as tracked repo (preserves .git for updates) |
--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 skill by name (uses stored source metadata)
skillshare install my-skill --update
# Update from source URL directly
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, tracked repos, and their sources.
skillshare list # List all skills and tracked repos
skillshare list --verbose # Show detailed info (source, type, install date)
Example output:
Installed skills
-------------------------------------------------------
my-skill (local)
_team-repo__frontend__ui (tracked: _team-repo)
personal__writing__email (local)
Tracked repositories
-------------------------------------------------------
_team-repo 5 skills, up-to-date
Update Skills
Update skills or tracked repositories.
# Update regular skills (reinstalls from stored source)
skillshare update my-skill # Update skill from its source
skillshare update my-skill --dry-run # Preview update
# Update tracked repos (git pull)
skillshare update _team-repo # Update specific repo
skillshare update team-repo # _ prefix is optional
skillshare update --all # Update all tracked repos
After updating, run skillshare sync to distribute changes to all targets.
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. target addfails with "path does not exist": create the directory first withmkdir -p <path>.
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

