Files
skillshare/website/docs/concepts/sync-modes.md
T
2026-02-01 22:52:11 +08:00

3.4 KiB

sidebar_position
sidebar_position
3

Sync Modes

How skillshare links source to targets.

Overview

Mode Behavior Use Case
merge Each skill symlinked individually Default. Preserves local skills.
symlink Entire directory is one symlink Exact copies everywhere.

Merge Mode (Default)

Each skill is symlinked individually. Local skills in the target are preserved.

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/                         ~/.claude/skills/
├── my-skill/        ────────►  ├── my-skill/ → (symlink)
├── another/         ────────►  ├── another/  → (symlink)
└── ...                         ├── local-only/  (preserved)
                                └── ...

Advantages:

  • Keep target-specific skills (not synced)
  • Mix installed and local skills
  • Granular control

When to use:

  • You want some skills only in specific AI CLIs
  • You want to try local skills before syncing

The entire target directory is a single symlink to source.

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/              ────────►  ~/.claude/skills → (symlink to source)
├── my-skill/
├── another/
└── ...

Advantages:

  • All targets are identical
  • Simpler to manage
  • No orphaned symlinks

When to use:

  • You want all AI CLIs to have exactly the same skills
  • You don't need target-specific skills

Warning: In symlink mode, deleting through target deletes source!

rm -rf ~/.claude/skills/my-skill  # ❌ Deletes from SOURCE
skillshare target remove claude   # ✅ Safe way to unlink

Changing Mode

Per-target

# Switch to symlink mode
skillshare target claude --mode symlink
skillshare sync

# Switch back to merge mode
skillshare target claude --mode merge
skillshare sync

Default mode

Set in config for new targets:

# ~/.config/skillshare/config.yaml
mode: merge  # or symlink

targets:
  claude:
    path: ~/.claude/skills
    # inherits default mode

  codex:
    path: ~/.codex/skills
    mode: symlink  # override default

Mode Comparison

Aspect Merge Symlink
Local skills preserved ✅ Yes ❌ No
All targets identical ❌ Can differ ✅ Yes
Orphan cleanup needed ✅ Yes ❌ No
Delete safety ✅ Safe ⚠️ Caution
Complexity Higher Lower

In merge mode, when you remove a skill from source, the target symlinks become "orphaned" (pointing to nothing).

Handling: skillshare sync automatically prunes orphaned symlinks:

$ skillshare sync
✓ claude: merged (5 linked, 2 local, 0 updated, 1 pruned)
                                                  ^^^^^^^^