Skip to main content

From Existing Skills

You already have skills scattered across ~/.claude/skills/, ~/.cursor/skills/, or other AI CLI directories. This guide consolidates them into a single source and replaces the originals with symlinks.

BEFORE                                  AFTER
─────────────────────────────────────────────────────────────────
~/.claude/skills/                       Source (one source of truth)
  ├── skill-a/                          ~/.config/skillshare/skills/
  └── skill-b/                            ├── skill-a/
                                          ├── skill-b/
~/.cursor/skills/                         ├── skill-c/
  ├── skill-b/  (duplicate!)              └── skill-d/
  └── skill-c/
                                        Targets (symlinked back)
~/.codex/skills/                        ~/.claude/skills/ → source
  └── skill-d/                          ~/.cursor/skills/ → source
                                        ~/.agents/skills/ → source
Back up first

collect mutates target directories — local skills get replaced with symlinks. Always run skillshare backup before collecting so skillshare restore <target> can undo it if anything looks wrong afterwards.

Which path applies​

Your situationPath
Skills live in one CLI onlySingle-CLI migration
Skills are spread across multiple CLIsMulti-CLI consolidation
You already have a skills git repo elsewhereConnect an existing repo

Single-CLI migration​

If every skill lives in a single target (say, Claude), init --copy-from handles it in one step:

skillshare init --copy-from claude
skillshare sync

--copy-from claude copies every skill from ~/.claude/skills/ into source during init. The subsequent sync replaces the originals with symlinks pointing back at source.

Multi-CLI consolidation​

Skills are scattered across multiple targets. Initialize empty, snapshot, then collect from each target.

# 1. Initialize empty
skillshare init --no-copy

# 2. Snapshot every target before mutating it
skillshare backup

# 3. Collect — once for everything, or per target
skillshare collect --all
#   or:
#   skillshare collect claude
#   skillshare collect cursor

# 4. Sync — targets now symlink back to source
skillshare sync

What collect does to each target:

  1. Copies non-symlinked local skills into source (skips any .git/ inside a skill).
  2. Replaces the originals with symlinks pointing back at source.
  3. Detects duplicates (the same skill name appearing in multiple targets) and reports them without overwriting.

Skills are copied into source, and each original becomes a link back:

Resolving duplicates​

When a skill exists in source and in a target you're collecting from, the target version is skipped and reported:

Warning: skill-b exists in source
  Source:  ~/.config/skillshare/skills/skill-b/
  Skipped: ~/.cursor/skills/skill-b/

Resolve by hand: diff the two copies, keep whichever you want in source, then either leave the target version alone (it'll be replaced by the symlink on next sync) or re-run collect --force if the target version is the one you'd rather keep.

Connect an existing repo​

If you already have a skills repo on GitHub (perhaps from a previous machine), don't collect — just clone it:

skillshare init --remote git@github.com:you/skills.git --all-targets --no-skill
skillshare sync

Tracked dependencies are gitignored and won't come down with the clone. Re-install them after init:

skillshare install https://github.com/your-company/skills --track --force
skillshare sync

Push your migrated source to git​

After migration, get source under version control so future machines can recover it the same way.

# Skip this if you already passed --remote during init.
cd ~/.config/skillshare/skills
git remote add origin git@github.com:you/skills.git

skillshare push -m "Initial commit: migrated skills"

From then on, skillshare push and skillshare pull move skills between machines.

Verify​

skillshare status     # every target should report 'synced'
skillshare list       # all collected skills should appear
skillshare doctor     # diagnostics — broken symlinks, missing targets, etc.

Rollback​

Because you ran backup first, collect is reversible:

skillshare restore claude
skillshare restore cursor

Each target returns to its pre-collect state — real files, no symlinks.

See Also​