Files
skillshare/website/docs/understand/philosophy/sync-modes-explained.md
T
Willie caa525b8aa feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
Restructure the entire documentation site following the Diátaxis framework
(Learn / How-to / Understand / Reference) with new content across 110 files.

## Information Architecture (M1)
- Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/)
- Add client-redirects plugin for old URL compatibility
- Rewrite sidebar, navbar, and footer to match new IA
- Update all internal cross-references

## Homepage + Quickstarts (M2)
- Add scenario entry cards to homepage with hand-drawn design
- 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation),
  Codex, Multiple Tools, Dev Containers, Playground

## Blog + Changelog (M3)
- Enable Docusaurus blog plugin with authors.yml
- 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills
  comparison, team sharing patterns, write your first skill
- Static /changelog page from CHANGELOG.md

## Recipes + Philosophy (M4)
- 5 recipe pages: CI/CD validation, enterprise skills, project setup,
  cross-machine sync, team onboarding
- 3 philosophy pages: why-local-first, security-first, sync-modes-explained

## Content Polish
- Cross-validate all content against CLI source (19 inaccuracies fixed)
- Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.)
- Add registry.yaml to file structure and Key Paths docs
- Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea,
  Azure DevOps, AtomGit, Codeberg)
- Standardize brew install command
- Add AsciinemaPlayer component (cast recordings pending)
2026-02-26 22:27:23 +08:00

4.9 KiB

sidebar_position
sidebar_position
5

Sync Modes Explained

A deep dive into the three sync modes — merge, copy, and symlink — when to use each, and the trade-offs.

The Three Modes

skillshare offers three sync modes that control how skills are delivered from your source directory to AI tool target directories.

Merge Mode (Default)

Source: ~/.config/skillshare/skills/
├── code-review/SKILL.md
├── testing/SKILL.md
└── debugging/SKILL.md

Target: ~/.claude/skills/
├── code-review → ~/.config/skillshare/skills/code-review  (symlink)
├── testing → ~/.config/skillshare/skills/testing           (symlink)
├── debugging → ~/.config/skillshare/skills/debugging       (symlink)
└── my-local-skill/SKILL.md                                 (untouched)

How it works: Creates one symlink per skill. Each skill directory in the target points back to the source.

Key property: Non-destructive. Local skills in the target directory (like my-local-skill above) are preserved. skillshare only manages symlinks it created.

Copy Mode

Source: ~/.config/skillshare/skills/
├── code-review/SKILL.md
├── testing/SKILL.md
└── debugging/SKILL.md

Target: ~/.cursor/skills/
├── code-review/SKILL.md                (physical copy)
├── testing/SKILL.md                    (physical copy)
├── debugging/SKILL.md                  (physical copy)
├── .skillshare-manifest.json           (tracks managed files)
└── my-local-skill/SKILL.md             (untouched)

How it works: Physically copies each skill into the target. A .skillshare-manifest.json file tracks which skills are managed and their SHA-256 checksums. On subsequent syncs, only changed skills are re-copied.

Key property: Maximum compatibility. Works everywhere — no symlink support required. Local skills are preserved just like merge mode.

Source: ~/.config/skillshare/skills/
├── code-review/SKILL.md
├── testing/SKILL.md
└── debugging/SKILL.md

Target: ~/.claude/skills → ~/.config/skillshare/skills/  (single symlink)

How it works: Replaces the entire target directory with a single symlink pointing to the source.

Key property: Total control. The target is exactly the source. No local skills can exist in the target.

When to Use Each

Factor Merge Copy Symlink
Preserves local skills Yes Yes No
Cross-platform support May have issues Works everywhere May have issues
Source changes reflected Instantly After sync Instantly
Handles nested paths Flattens (a/b/c → a__b__c) Flattens Native structure
Orphan cleanup Automatic Automatic Not needed
Disk usage Minimal (symlinks) Full copies Minimal (one symlink)
Recommended for Most users WSL, Docker, CI Single-source setups

Choose Merge When

  • You have local skills in your AI tool that you don't want managed by skillshare
  • You use multiple AI tools with different local customizations
  • You're adopting skillshare incrementally (some skills managed, some not)

Choose Copy When

  • Your platform has unreliable symlink support (WSL, some Docker setups)
  • The AI tool doesn't follow symlinks correctly
  • You're in a CI/CD pipeline or containerized environment
  • You want the target to work independently of the source directory
  • skillshare is the only source of skills for a target
  • You want zero ambiguity about what's in the target
  • You're setting up a fresh environment

Nested Path Handling

In merge and copy modes, nested source paths are flattened using double underscores:

Source: skills/frontend/react-patterns/SKILL.md
Target: ~/.claude/skills/frontend__react-patterns → skills/frontend/react-patterns

This avoids directory creation in targets that expect a flat skill structure. In symlink mode, the directory structure is preserved as-is.

Orphan Cleanup

Merge and copy modes automatically remove orphaned entries during skillshare sync. If you uninstall a skill from your source, the corresponding symlink (or copied directory) in the target is cleaned up on the next sync.

skillshare uninstall old-skill
skillshare sync
# → Pruned orphan: old-skill

Per-Target Mode Override

You can set different modes per target. Global config uses map format:

targets:
  claude:
    path: ~/.claude/skills
    mode: merge
  cursor:
    path: ~/.cursor/skills
    mode: copy

Project config uses list format:

targets:
  - name: claude
    mode: merge
  - name: cursor
    mode: copy

Or change mode via CLI:

skillshare target claude --mode copy