16 KiB
sidebar_position
| sidebar_position |
|---|
| 2 |
sync
Push skills from source to all targets.
:::info Why is sync a separate command?
Operations like install and uninstall only modify source — sync propagates to targets. This lets you batch changes, preview with --dry-run, and control when targets update. See Why Sync is a Separate Step.
:::
When to Use
- After installing, uninstalling, or editing skills — propagate changes to all targets
- After changing a target's sync mode — apply the new mode
- Periodically to ensure all targets are in sync
Command Overview
| Type | Command | Direction |
|---|---|---|
| Local sync | sync / collect |
Source ↔ Targets |
| Remote sync | push / pull |
Source ↔ Git Remote |
sync= Distribute from Source to Targetscollect= Collect from Targets back to Sourcepush= Push to git remotepull= Pull from git remote and sync
Overview
flowchart TD
REMOTE["`Remote
(git)`"]
SOURCE["`SOURCE
~/.config/skillshare/skills/`"]
CLAUDE["Claude"]
CURSOR["Cursor"]
CODEX["Codex"]
SOURCE -- push --> REMOTE
REMOTE -- pull --> SOURCE
SOURCE -- sync --> CLAUDE
SOURCE -- sync --> CURSOR
SOURCE -- sync --> CODEX
CLAUDE -- collect --> SOURCE
CURSOR -- collect --> SOURCE
CODEX -- collect --> SOURCE
| Command | Direction | Description |
|---|---|---|
sync |
Source → Targets | Push skills to all targets |
collect <target> |
Target → Source | Collect skills from target to source |
push |
Source → Remote | Commit and push to git |
pull |
Remote → Source → Targets | Pull from git, then sync |
Project Mode
When .skillshare/config.yaml exists in the current directory, sync auto-detects project mode:
cd my-project/
skillshare sync # Auto-detected project mode
skillshare sync -p # Explicit project mode
Project sync defaults to merge mode (per-skill symlinks), but each target can be set to copy or symlink mode via skillshare target <name> --mode copy -p. Backup is not created (project targets are reproducible from source).
.skillshare/skills/ .claude/skills/
├── my-skill/ ────────► ├── my-skill/ → (symlink)
├── pdf/ ────────► ├── pdf/ → (symlink)
└── ... └── local/ (preserved)
Sync
Push skills from source to all targets.
skillshare sync # Sync skills to all targets
skillshare sync --all # Sync skills + extras
skillshare sync --dry-run # Preview changes
skillshare sync -n # Short form
skillshare sync --force # Overwrite all managed skills
skillshare sync -f # Short form
| Flag | Short | Description |
|---|---|---|
--all |
Also sync extras after skills (see sync extras below) | |
--dry-run |
-n |
Preview changes without writing |
--force |
-f |
Overwrite all managed entries regardless of checksum (copy mode) or replace existing directories with symlinks (merge mode) |
--json |
Output as JSON |
JSON Output
skillshare sync --json
{
"targets": 3,
"linked": 12,
"local": 2,
"updated": 0,
"pruned": 1,
"dry_run": false,
"duration": "0.234s",
"details": [
{
"name": "claude",
"mode": "merge",
"linked": 8,
"local": 2,
"updated": 0,
"pruned": 1
},
{
"name": "cursor",
"mode": "merge",
"linked": 4,
"local": 0,
"updated": 0,
"pruned": 0
}
]
}
What Happens
flowchart TD
TITLE["skillshare sync"]
S1["1. Backup targets (global only)"]
S2["2. For each target"]
MERGE["merge mode"]
SYMLINK["symlink mode"]
S3["3. Report results"]
TITLE --> S1 --> S2
COPY["copy mode"]
S2 --> MERGE --> S3
S2 --> COPY --> S3
S2 --> SYMLINK --> S3
Example Output
Collect
Collect skills from a target back to source.
skillshare collect claude # Collect from Claude
skillshare collect claude --dry-run # Preview
skillshare collect --all # Collect from all targets
When to use: You created/edited a skill directly in a target (e.g., ~/.claude/skills/) and want to bring it to source.
flowchart TD
TITLE["skillshare collect claude"]
S1["1. Find local skills in target"]
S2["2. Copy to source"]
S3["3. Replace with symlink"]
TITLE --> S1 --> S2 --> S3
After collecting:
skillshare collect claude
skillshare sync # ← Distribute to other targets
Pull
Pull from git remote and sync to all targets.
skillshare pull # Pull from git remote
skillshare pull --dry-run # Preview
When to use: You pushed changes from another machine and want to sync them here.
flowchart TD
TITLE["skillshare pull"]
S1["1. git pull"]
S2["2. skillshare sync"]
TITLE --> S1 --> S2
Push
Commit and push source to git remote.
skillshare push # Auto-generated message
skillshare push -m "Add pdf" # Custom message
flowchart TD
TITLE["skillshare push -m 'Add pdf skill'"]
S1["`cd source
git add → commit → push`"]
TITLE --> S1
Conflict handling:
- If remote is ahead,
pushfails → runpullfirst
Dotfiles Manager Compatibility
If you use a dotfiles manager (GNU Stow, chezmoi, yadm, bare-git) that symlinks your source or target directories, skillshare handles it transparently:
# Dotfiles manager creates:
~/.config/skillshare/skills/ → ~/dotfiles/ss-skills/ # symlinked source
~/.claude/skills/ → ~/dotfiles/claude-skills/ # symlinked target
- Symlinked source — all commands (
sync,update,uninstall,list,diff,install) resolve the symlink before walking, so skills are discovered correctly. Chained symlinks (link → link → real dir) also work. - Symlinked target —
syncdetects that the target symlink was not created by skillshare and preserves it. Skills are synced into the resolved directory. - Status/collect —
statusandcollectfollow external target symlinks instead of reporting conflicts.
:::info How sync decides When a target directory is a symlink, sync checks whether it points to the skillshare source directory. Only symlinks created by skillshare's own symlink mode are removed during mode conversion — external symlinks (from dotfiles managers) are always preserved. :::
Sync Modes
| Mode | Behavior | Use case |
|---|---|---|
merge |
Each skill symlinked individually | Default. Preserves local skills. |
copy |
Each skill copied as real files | Compatibility-first setups, vendoring skills into a project repo, or environments where symlink behavior is unreliable. |
symlink |
Entire directory is one symlink | Exact copies everywhere. |
Per-target override remains the primary tuning knob:
skillshare target <name> --mode copy
skillshare sync
When sync prints a compatibility hint, the example target is chosen in this priority:
cursor → antigravity → copilot → opencode.
If none of these targets exist (or they already run copy), no compatibility hint is shown.
See Sync Modes for a neutral decision matrix.
Per-target include/exclude filters
In merge and copy modes, each target can define include / exclude patterns in config:
targets:
codex:
path: ~/.codex/skills
include: [codex-*]
claude:
path: ~/.claude/skills
exclude: [codex-*]
- Matching is against flat target names (for example
team__frontend__ui) includeis applied first, thenexcludediff,status,doctor, and UI drift all use the filtered expected set- In symlink mode, filters are ignored
- In copy mode, filters work the same way as merge mode
syncremoves existing source-linked or managed entries that are now excluded
See Configuration for full details.
Filter behavior examples
Assume source contains:
core-authcore-docscodex-agentcodex-experimentalteam__frontend__ui
include only
targets:
codex:
path: ~/.codex/skills
include: [codex-*, core-*]
After sync, codex receives:
core-authcore-docscodex-agentcodex-experimental
Use this when a target should receive only a curated subset.
exclude only
targets:
claude:
path: ~/.claude/skills
exclude: [codex-*, *-experimental]
After sync, claude receives:
core-authcore-docsteam__frontend__ui
Use this when a target should get "almost everything" except specific groups.
include + exclude
targets:
cursor:
path: ~/.cursor/skills
include: [core-*, codex-*]
exclude: [*-experimental]
After sync, cursor receives:
core-authcore-docscodex-agent
codex-experimental is first included, then removed by exclude.
What gets removed when filters change
When a filter is updated and sync runs:
- Source-linked entries (symlink/junction) that are now filtered out are pruned
- Local non-symlink folders already in target are preserved
Merge Mode (Default)
Source Target (claude)
─────────────────────────────────────────────────────────────
skills/ ~/.claude/skills/
├── my-skill/ ────────► ├── my-skill/ → (symlink)
├── another/ ────────► ├── another/ → (symlink)
└── ... ├── local-only/ (preserved)
└── .skillshare-manifest.json
Copy Mode
Source Target (cursor)
─────────────────────────────────────────────────────────────
skills/ ~/.cursor/skills/
├── my-skill/ ────copy► ├── my-skill/ (real files)
├── another/ ────copy► ├── another/ (real files)
└── ... ├── local-only/ (preserved)
└── .skillshare-manifest.json
Both merge and copy modes write .skillshare-manifest.json to track managed skills. In copy mode, checksums enable incremental sync (unchanged skills are skipped); --force overwrites all.
Symlink Mode
Source Target (claude)
─────────────────────────────────────────────────────────────
skills/ ────────► ~/.claude/skills → (symlink to source)
├── my-skill/
├── another/
└── ...
Change Mode
skillshare target claude --mode merge
skillshare target claude --mode copy
skillshare target claude --mode symlink
skillshare sync # Apply change
Safety 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
Backup
Backups are created automatically before sync and target remove.
Location: ~/.local/share/skillshare/backups/<timestamp>/
Manual Backup
skillshare backup # Backup all targets
skillshare backup claude # Backup specific target
skillshare backup --list # List all backups
skillshare backup --cleanup # Remove old backups
skillshare backup --dry-run # Preview
Example Output
$ skillshare backup --list
Backups
─────────────────────────────────────────
2026-01-20_15-30-00/
claude/ 5 skills, 2.1 MB
cursor/ 5 skills, 2.1 MB
2026-01-19_10-00-00/
claude/ 4 skills, 1.8 MB
Restore
Restore targets from backup.
skillshare restore claude # Latest backup
skillshare restore claude --from 2026-01-19_10-00-00 # Specific backup
skillshare restore claude --dry-run # Preview
flowchart TD
CMD["skillshare restore claude"]
FIND["1. Find latest backup"]
REMOVE["2. Remove current target"]
COPY["3. Copy backup to target"]
CMD --> FIND --> REMOVE --> COPY
Sync Extras
Sync non-skill resources (rules, commands, prompts, etc.) to arbitrary directories. Extras are configured separately from skills and have their own source directories.
skillshare sync extras # Sync all configured extras
skillshare sync extras --dry-run # Preview changes
skillshare sync extras --force # Overwrite conflicting files
skillshare sync --all # Sync skills + extras in one command
| Flag | Short | Description |
|---|---|---|
--dry-run |
-n |
Preview changes without writing |
--force |
-f |
Overwrite conflicting files at target |
:::info Global only
sync extras is global-only. The --all flag is ignored in project mode.
:::
Configuration
Add an extras section to your global config (~/.config/skillshare/config.yaml):
extras:
- name: rules
targets:
- path: ~/.claude/rules
- path: ~/.cursor/rules
mode: copy
- name: commands
targets:
- path: ~/.claude/commands
Each extra has:
name— directory name under~/.config/skillshare/(the source)targets— list of target paths with optionalmode
Source files live alongside your skills directory:
~/.config/skillshare/
├── config.yaml
├── skills/ ← skill source
├── rules/ ← extras source (name: rules)
│ ├── coding.md
│ └── testing.md
└── commands/ ← extras source (name: commands)
└── deploy.md
Sync modes
| Mode | Behavior |
|---|---|
merge |
Per-file symlink from target to source (default) |
copy |
Per-file copy |
symlink |
Entire source directory symlinked to target path |
In merge mode, only symlinks are pruned — user-created local files at the target are preserved.
What happens
flowchart TD
CMD["skillshare sync extras"]
WALK["1. Discover files in source"]
EACH["2. For each target"]
SYNC["Sync files (symlink/copy)"]
PRUNE["3. Prune orphans"]
CMD --> WALK --> EACH --> SYNC --> PRUNE
- Walks the source directory (
~/.config/skillshare/<name>/) - For each target, creates symlinks or copies per configured mode
- Removes orphan files in the target that no longer exist in source
Example output
$ skillshare sync extras
Rules
✔ ~/.claude/rules 2 files linked (merge)
✔ ~/.cursor/rules 2 files copied (copy)
Commands
✔ ~/.claude/commands 1 files linked (merge)
See Also
- status — Show sync state
- diff — Show differences
- Targets — Manage targets
- Cross-Machine Sync — Sync across computers
- install — Install skills
- Configuration — Extras config reference
