Skip to main content

Migration

Migrate from other skill management approaches to skillshare.

From Manual Management​

If you've been manually copying skills between AI CLIs:

Step 1: Initialize skillshare​

skillshare init

Step 2: Collect existing skills​

# Collect from each AI CLI
skillshare collect claude
skillshare collect pi
skillshare collect codex

# Or collect from all at once
skillshare collect --all

Step 3: Handle duplicates​

If the same skill exists in multiple places, collect warns you. Choose which to keep.

Step 4: Sync​

skillshare sync

Now all targets are symlinked to your single source.

From Other Install Tools​

If you've used npx install-skill or similar:

Step 1: Initialize skillshare​

skillshare init

Step 2: Backup existing skills​

skillshare backup

Step 3: Collect or reinstall​

Option A: Collect existing (keeps current versions)

skillshare collect --all

Option B: Reinstall from source (gets latest versions)

# Check the metadata
cat ~/.config/skillshare/skills/.metadata.json

# Reinstall
skillshare install anthropics/skills/skills/pdf

Step 4: Sync​

skillshare sync

From npx skills​

If you installed skills with the npx skills CLI (npx skills add ...), skillshare can take over the same directories. You can also run both tools side by side and only move the skills you want managed.

Where npx skills keeps things:

ItemGlobalProject
Skill files~/.agents/skills/<name>/ (real directories).agents/skills/<name>/
Agent directoriesSymlinks to the files above (for example ~/.claude/skills/<name>)Same
Lock file~/.agents/.skill-lock.json (or $XDG_STATE_HOME/skills/.skill-lock.json)skills-lock.json

Skills installed with --copy are real directories in each agent directory instead of symlinks.

Step 1: Initialize skillshare​

skillshare init

Step 2: Backup existing skills​

skillshare backup

Step 3: Collect the skills​

collect copies real directories and skips symlinks, so the symlinks in agent directories are not collected twice.

skillshare collect universal --dry-run   # Preview
skillshare collect universal             # ~/.agents/skills

If you used --copy or have skills in other agent directories, run skillshare collect --all instead and resolve duplicates as described in From Manual Management.

Collected skills are plain local copies. They do not remember which repository they came from, so skillshare update cannot update them.

Step 4: Reinstall skills you want to keep updating (optional)​

The lock file records where each skill came from. source is the repository and skillPath is the location inside it.

cat ~/.agents/.skill-lock.json

# "source": "anthropics/skills", "skillPath": "skills/pdf/SKILL.md"
skillshare install anthropics/skills/skills/pdf

Use --force if the skill already exists in your source from Step 3.

Step 5: Sync​

skillshare sync

In merge mode, sync keeps a real directory of the same name in the target (~/.agents/skills) and reports it as a preserved local skill. The npx skills symlinks in other agent directories, such as ~/.claude/skills, are repointed to your skillshare source. To also replace the real directories with symlinks, run this after Step 3 has collected them:

skillshare sync --force

sync --force backs up the target before replacing anything. After this, manage those skills with skillshare only. npx skills tracks installs in its own lock file, so avoid running npx skills update or npx skills remove on them.

For a project that uses npx skills, follow From Committed Project Skills with .agents/skills/ as the directory to move.

From Git Submodules​

If you've been using git submodules:

Step 1: Export submodule contents​

# In your existing skills repo
git submodule foreach 'cp -r $toplevel/$sm_path ~/temp-skills/$name'

Step 2: Initialize skillshare​

skillshare init

Step 3: Import skills​

# Copy to source
cp -r ~/temp-skills/* ~/.config/skillshare/skills/

# Or install as tracked repos
skillshare install github.com/org/skill-repo --track

Step 4: Sync​

skillshare sync

From Committed Project Skills​

If your repo already has skills committed in .claude/skills/, .cursor/skills/, or similar directories:

Step 1: Initialize project mode​

cd my-project
skillshare init -p

Step 2: Move skills to .skillshare/skills/​

# Copy existing skills to skillshare source
cp -r .claude/skills/my-skill .skillshare/skills/
cp -r .claude/skills/api-guide .skillshare/skills/

# Remove originals (sync will recreate as symlinks)
rm -rf .claude/skills/my-skill .claude/skills/api-guide

Step 3: Sync​

skillshare sync

Now .claude/skills/my-skill is a symlink to .skillshare/skills/my-skill — and all other targets (Pi, Windsurf, etc.) get the same skills automatically.

Step 4: Commit the migration​

git add .skillshare/ .claude/skills/ .cursor/skills/
git commit -m "Migrate project skills to skillshare"
Multi-Tool Benefit

Before: skills only worked in one AI CLI. After: the same skills are automatically available in every configured target.

From Team-Specific Solutions​

If your team has custom skill sharing:

Step 1: Identify current approach​

  • Where are skills stored?
  • How are they shared?
  • How are they updated?

Step 2: Choose your migration path​

Option A: Global mode — skills available across all projects on each machine.

# Create team skills repo
cp -r /current/team/skills ~/new-team-skills
cd ~/new-team-skills && git init && git add . && git commit -m "Migrate to skillshare"
git push origin main

# Team members install globally
skillshare install github.com/org/team-skills --track && skillshare sync

Option B: Project mode — skills scoped to a specific repo, shared via git.

cd my-project
skillshare init -p

# Move team skills into project source
cp -r /current/team/skills/* .skillshare/skills/

# Sync and commit
skillshare sync
git add .skillshare/
git commit -m "Add team skills via skillshare"

New team members get everything with:

git clone github.com/org/my-project
cd my-project
skillshare install -p && skillshare sync

Option C: Both — organization-wide standards globally, project-specific skills per-repo.

# Organization standards (global)
skillshare install github.com/org/standards --track && skillshare sync

# Project-specific skills (project mode)
cd my-project
skillshare init -p
skillshare install github.com/org/project-skills -p && skillshare sync
Which to Choose?
  • Global: coding standards, security audits — things every project needs
  • Project: API conventions, domain rules, deployment guides — things specific to one repo
  • Both: most teams end up here as they grow

From Global to Project​

If you have skills in global mode that belong to a specific project:

Step 1: Initialize project mode​

cd my-project
skillshare init -p

Step 2: Copy skills from global source​

# Copy specific skills
cp -r ~/.config/skillshare/skills/api-guide .skillshare/skills/
cp -r ~/.config/skillshare/skills/deploy-rules .skillshare/skills/

Step 3: Remove from global (optional)​

skillshare uninstall api-guide
skillshare uninstall deploy-rules
skillshare sync   # Clean up global symlinks

Step 4: Sync and commit​

skillshare sync   # Auto-detects project mode
git add .skillshare/
git commit -m "Move project-specific skills to project mode"

After this, the skills are scoped to this repo and shared with the team via git — no longer cluttering your global setup.

Preserving History​

If you want to keep git history:

For personal skills​

# Clone your existing repo to skillshare location
git clone your-existing-repo ~/.config/skillshare/skills

# Initialize skillshare with existing source
skillshare init --source ~/.config/skillshare/skills

For team repos​

# Use --track to preserve .git
skillshare install github.com/team/skills --track

Rollback​

If migration goes wrong:

Restore from backup​

skillshare restore claude
skillshare restore cursor

Start fresh​

rm ~/.config/skillshare/config.yaml
skillshare init

Checklist​

Before migrating:

  • List all current skill locations
  • Identify duplicates
  • Note any custom configurations
  • Create backups

After migrating:

  • Verify all skills appear in skillshare list
  • Test skills in each AI CLI
  • Set up git remote (if desired)
  • Share new workflow with team

See Also​