Files
skillshare/website/docs/how-to/advanced/migration.md
T
Willie 0ff337899c docs(migration): add a path for moving from npx skills
Users who installed skills with npx skills had no migration steps; the FAQ only covered running both tools side by side. The new section maps where npx skills keeps its files and lock file, then walks through backup, collect, optional reinstall from the lock file, and sync. Behavior was checked in an isolated devcontainer environment: collect skips symlinks, plain sync preserves real directories in the universal target, and sync --force replaces them after backing up the target. Translated for zh-Hant, zh-Hans, ja and ko.
2026-09-29 04:12:03 +08:00

9.2 KiB

sidebar_position
sidebar_position
5

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 cursor
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:

Item Global Project
Skill files ~/.agents/skills/<name>/ (real directories) .agents/skills/<name>/
Agent directories Symlinks 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 (Cursor, 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"

:::tip 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

:::tip 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