Files
skillshare/website/docs/reference/commands/sync.md
T
Willie 49a52498e9 docs: add current screenshots and diagrams to the guides
The dashboard screenshots predated the Projects page and showed codex at
its old path, and the guides for dashboard-only features (AGENTS.md
sharing, MCP, plugins, backups, hubs) had no pictures at all.

- Re-shoot the dashboard screenshots (docs and README copies) and add
  ones for targets, extras, shared AGENTS.md, MCP, project MCP, plugins,
  backups, hubs and project mode.
- Add diagrams for sharing AGENTS.md, MCP sync and migrating with
  collect; fix codex's path in the getting-started diagram.
- Replace terminal screenshots with real output as text, and remove
  images nothing referenced.
- Fix text that no longer matched the dashboard (project mode, hub
  navigation, backup list output).
2026-09-28 21:02:12 +08:00

728 lines
23 KiB
Markdown

---
sidebar_position: 2
---
# sync
Push skills from source to all targets.
Use `skillshare sync mcp` for MCP connection settings, or `skillshare sync --all`
to include skills, agents, extras and MCP. MCP synchronization uses entry
ownership and conflict checks rather than skill symlinks. See [mcp](/docs/reference/commands/mcp).
:::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](/docs/understand/source-and-targets#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 Targets
- `collect` = Collect from Targets back to Source
- `push` = Push to git remote
- `pull` = Pull from git remote and sync
## Overview
```mermaid
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:
```bash
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)
```
### Cleanup after a default path moves {#project-path-cleanup}
A project config stores target names, not paths, so a target follows its built-in
default. When a tool changes that default — as goose and openhands did when they
adopted `.agents/skills` — the skills skillshare wrote to the old directory stay
behind, and the tool reads both locations and lists every skill twice.
Project sync removes them. For each target without an explicit `path:`, it looks
at the directories that target's runtime also scans, and in any of them that no
configured target writes to, it removes the entries skillshare created. Folders
you made yourself and symlinks pointing outside the project are never touched.
```
→ Cleaned 1 leftover skill(s) from .goose/skills: the default path for 'goose' moved to .agents/skills
```
Setting an explicit `path:` for a target opts it out of the cleanup, and
`--dry-run` previews what would be removed without changing anything.
---
## Sync
Push skills from source to all targets.
```bash
skillshare sync # Sync skills to all targets
skillshare sync agents # Sync agents only
skillshare sync --all # Sync skills + agents + extras + MCP
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 agents, extras, and MCP after skills (excludes plugins) |
| `--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 |
| `--quiet` | `-q` | Suppress token summary and budget warnings |
### JSON Output
```bash
skillshare sync --json
```
```json
{
"targets": 3,
"linked": 12,
"local": 2,
"updated": 0,
"pruned": 1,
"ignored_count": 2,
"ignored_skills": ["_team/vendor/lib", "test-draft"],
"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
}
],
"context_cost": {
"groups": [
{
"targets": ["claude", "cursor"],
"always_loaded_tokens": 12400,
"on_demand_tokens": 58200
}
]
}
}
```
The `ignored_count` and `ignored_skills` fields show skills excluded by `.skillignore` (and `.skillignore.local` if present). These are filtered at discovery time and never reach any target. When `.skillignore.local` is active, the text output includes a `.local` source hint. See [.skillignore](/docs/reference/appendix/file-structure#skillignore-optional) for pattern syntax.
### What Happens
```mermaid
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
```text
$ skillshare sync
✓ Discovered 43 skills
Backing up
─────────────────────────────────────────
✓ claude -> ~/.local/share/skillshare/backups/2026-09-28_12-52-50/claude
✓ cursor -> ~/.local/share/skillshare/backups/2026-09-28_12-52-50/cursor
✓ gemini -> ~/.local/share/skillshare/backups/2026-09-28_12-52-50/gemini
…
Syncing skills
─────────────────────────────────────────
✓ claude: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ claude-work: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ cursor: merged (43 linked, 1 local, 0 updated, 1 pruned)
✓ gemini: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ opencode: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ universal: merged (43 linked, 0 local, 0 updated, 1 pruned)
Sync complete: 6 targets, 258 linked, 1 local, 0 updated, 6 pruned (0.0s)
```
---
## Collect
Collect skills from a target back to source.
```bash
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.
```mermaid
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:**
```bash
skillshare collect claude
skillshare sync # ← Distribute to other targets
```
---
## Pull
Pull from git remote and sync to all targets.
```bash
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.
```mermaid
flowchart TD
TITLE["skillshare pull"]
S1["1. git pull"]
S2["2. skillshare sync"]
TITLE --> S1 --> S2
```
---
## Push
Commit and push source to git remote.
```bash
skillshare push # Auto-generated message
skillshare push -m "Add pdf" # Custom message
```
```mermaid
flowchart TD
TITLE["skillshare push -m 'Add pdf skill'"]
S1["`cd source
git add → commit → push`"]
TITLE --> S1
```
**Conflict handling:**
- If remote is ahead, `push` fails → run `pull` first
---
## Dotfiles Manager Compatibility {#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** — `sync` detects that the target symlink was **not** created by skillshare and preserves it. Skills are synced into the resolved directory.
- **Status/collect** — `status` and `collect` follow 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:
```bash
skillshare target <name> --mode copy
skillshare sync
```
The compatibility hint is printed by [`doctor`](./doctor.md), not by `sync`. Its 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](/docs/understand/sync-modes) for a neutral decision matrix.
### Per-target include/exclude filters {#per-target-includeexclude-filters}
In merge and copy modes, each target can define `include` / `exclude` patterns in config:
```yaml
targets:
codex:
path: ~/.codex/skills
include: [codex-*]
claude:
path: ~/.claude/skills
exclude: [codex-*]
```
- Matching is against flat target names (for example `team__frontend__ui`)
- `include` is applied first, then `exclude`
- `diff`, `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
- `sync` removes existing source-linked or managed entries that are now excluded
See [Configuration](/docs/reference/targets/configuration#include--exclude-target-filters) for full details.
:::tip
These are just one of three filtering layers. See [Filtering Skills](/docs/how-to/daily-tasks/filtering-skills) for a complete guide covering `.skillignore`, SKILL.md `targets`, and target filters.
:::
### Filter behavior examples {#filter-behavior-examples}
Assume source contains:
- `core-auth`
- `core-docs`
- `codex-agent`
- `codex-experimental`
- `team__frontend__ui`
#### `include` only
```yaml
targets:
codex:
path: ~/.codex/skills
include: [codex-*, core-*]
```
After `sync`, codex receives:
- `core-auth`
- `core-docs`
- `codex-agent`
- `codex-experimental`
Use this when a target should receive only a curated subset.
#### `exclude` only
```yaml
targets:
claude:
path: ~/.claude/skills
exclude: [codex-*, *-experimental]
```
After `sync`, claude receives:
- `core-auth`
- `core-docs`
- `team__frontend__ui`
Use this when a target should get "almost everything" except specific groups.
#### `include` + `exclude`
```yaml
targets:
cursor:
path: ~/.cursor/skills
include: [core-*, codex-*]
exclude: [*-experimental]
```
After `sync`, cursor receives:
- `core-auth`
- `core-docs`
- `codex-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
```bash
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!**
> ```bash
> 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>/`
A snapshot captures only **local** target content. Merge-mode symlinks are skipped — they point into your source and `sync` recreates them — so snapshots stay small no matter how large your skills are. Retention is applied automatically after each sync. See [What Gets Backed Up](/docs/reference/commands/backup#what-gets-backed-up) and [Backups & Disk Space](/docs/reference/commands/backup#backups--disk-space).
### Manual Backup
```bash
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.
```bash
skillshare restore claude # Latest backup
skillshare restore claude --from 2026-01-19_10-00-00 # Specific backup
skillshare restore claude --dry-run # Preview
```
```mermaid
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
```
---
## Agent Sync {#agent-sync}
Agents are synced separately from skills. Use `sync agents` for agent-only sync, or `sync --all` to include skills, agents, extras, and MCP:
```bash
skillshare sync # Sync skills only (default)
skillshare sync agents # Sync agents only
skillshare sync --all # Sync skills + agents + extras + MCP
```
Agent sync supports all three modes (merge, copy, symlink), matching the target's configured mode. On Windows without Developer Mode, merge mode copies agent files instead of linking them and prints `! <target>: agents file links need Windows Developer Mode; copying instead`; see [Windows troubleshooting](/docs/troubleshooting/windows#file-links-need-windows-developer-mode-copying-instead). Only targets with an `agents` path definition receive agent syncs — currently Claude, Cursor, OpenCode, and Augment. See [Agents — Supported Targets](/docs/understand/agents#supported-targets) for the full list.
Orphan cleanup, `.agentignore` filtering, and per-target include/exclude filters all work the same way as for skills.
---
## Sync Plugins
`sync plugins [name]` is an alias for [`plugin sync`](./plugin.md). Plugins are
**excluded from `sync --all`** and use native installation operations instead of
skill sync modes.
```bash
skillshare sync plugins --dry-run --json
skillshare sync plugins demo --target claude --no-tui
```
`plugin enable` and `plugin disable` save target selection only. The next plugin
sync installs selected bindings and uninstalls deselected ones while keeping their
definitions. Unmanaged plugins are unaffected. Plugin sync accepts `--target`,
`--dry-run`, `--json`, `--no-tui`, `--revision`, and mode flags; ordinary sync options
such as `--force`, `--quiet`, and `--all` do not apply. See [plugin](./plugin.md) for
native client requirements, project scope, and partial-failure recovery.
## Sync Extras {#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.
```bash
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 + agents + extras + MCP
```
| Flag | Short | Description |
|------|-------|-------------|
| `--dry-run` | `-n` | Preview changes without writing |
| `--force` | `-f` | Overwrite conflicting files at target |
`--json` returns a non-zero exit status when extras sync has errors. For single-file extras,
`--dry-run` also reports edits that would be backed up before replacement.
:::info Both modes supported
`sync extras` works in both global and project mode. Use `sync --all` to sync skills, agents, extras, and MCP together, or `sync extras` to sync extras only. In project mode, extras source is `.skillshare/extras/<name>/`.
:::
### Configuration
Add an `extras` section to your config (`~/.config/skillshare/config.yaml` for global, `.skillshare/config.yaml` for project):
```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 `extras/` in your config directory
- **`targets`** — list of target paths with optional `mode`
Source files live under the `extras/` subdirectory:
```
~/.config/skillshare/
├── config.yaml
├── skills/ ← skill source
└── extras/ ← extras source root
├── rules/ ← extras: rules
│ ├── coding.md
│ └── testing.md
└── commands/ ← extras: 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.
On Windows without Developer Mode, merge mode (and a [single-file extra](./extras.md#single-file-extras) in symlink mode) copies files instead, reports the target as `(copy)`, and prints `file links need Windows Developer Mode; copying instead` under it. These copies are updated and pruned like links, and replaced with links once file links work.
Identical local files are reported as `local preserved`; `sync extras` does not suggest `--force` for them. They remain local files, not managed links.
### What happens
```mermaid
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
```
1. Walks the source directory (`~/.config/skillshare/extras/<name>/`)
2. For each target, creates symlinks or copies per configured mode
3. 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)
```
---
## Context Cost {#context-cost}
After syncing, skillshare displays a token cost summary:
```
✔ Synced 47 skill(s) to 4 target(s) in 312ms
Context: ~12.4K always-loaded · ~58.2K on-demand (claude, cursor, codex, opencode)
```
- **Always-loaded**: frontmatter name + description (loaded every request)
- **On-demand**: skill body (loaded when triggered)
Targets with identical token counts are grouped on one line.
### Budget Warnings
Configure warning thresholds in your config:
```yaml
context_budget:
warn_always_loaded_tokens: 10000 # default; 0 = disabled
warn_on_demand_tokens: 100000 # default; 0 = disabled
```
When a threshold is exceeded, a warning appears with the top 3 offenders:
```
! Always-loaded context is ~50,123 tokens (budget: 10,000)
Top 3:
• my-big-skill ~8,200 tokens
• another-verbose-skill ~6,400 tokens
• chatgpt-system-prompt ~5,100 tokens
Run `skillshare analyze` for details.
```
### Quiet Mode
Use `--quiet` or `-q` to suppress token summary and budget warnings:
```bash
skillshare sync --quiet
```
JSON output (`--json`) always includes `context_cost` regardless of `--quiet`.
---
## See Also
- [status](/docs/reference/commands/status) — Show sync state
- [diff](/docs/reference/commands/diff) — Show differences
- [Targets](/docs/reference/targets) — Manage targets
- [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) — Sync across computers
- [install](/docs/reference/commands/install) — Install skills
- [Configuration](/docs/reference/targets/configuration#extras) — Extras config reference