mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
* fix(sync): never delete or re-point entries skillshare did not create On Windows, a plain `init` followed by `sync` deleted things in ~/.claude/skills that skillshare never created, with no backup and no prompt. It also re-pointed another tool's junction. Seen in a sandbox run of v0.30.7: - prune removed real folders whose names only look like skillshare's flat naming (team__shared, _drafts), via the name heuristic - prune removed a broken link that another tool or the user made - merge sync deleted and re-created a same-name link that pointed into another manager's store - init's import deleted original folders that matched the source byte for byte The manifest already records what skillshare made, so use it: - prune keeps a look-alike folder that is not in the manifest and warns once per sync; --force still removes it - prune removes a broken external link only if the manifest records it (e.g. after the source moved); otherwise it keeps the link and warns - merge sync re-points a link only if the manifest records it or it already points into the source; otherwise it reports the entry as kept local, as it already does for a real folder; --force replaces it - init's import moves identical copies to the trash under replaced-by-init/<target>/ instead of deleting them Tests: ownership_test.go adds regression tests that use createLink, so they run on Windows without Developer Mode (junctions). The 4 keep tests fail without this change. TestSyncTargetMerge_FixesBrokenLink now records the link in the manifest first, since a same-name link that skillshare did not make is no longer re-pointed. Existing tests in internal/sync, internal/trash and cmd/skillshare show the same failures on a Windows host with and without the change (symlink privilege). The devcontainer suite has not been run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: say what sync and init keep when skillshare did not create it The previous commit makes sync and init leave alone entries skillshare did not create. Update the pages that describe that behaviour: - sync-modes: merge mode keeps a same-name link from another tool and reports it as local; orphan cleanup keeps folders that only look like skillshare's flat names, and broken links outside the source that the manifest does not record. sync --force still removes them. - init: identical folders replaced with links during the first sync go to the trash first (replaced-by-init/<tool>/, cleaned after 7 days). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(sourcefs): drop the raw-write allowance replaceIdenticalCopies no longer needs replaceIdenticalCopies now moves an identical copy to the trash instead of calling os.RemoveAll, so TestRawWriteRatchet reports its allowance as stale. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(sync): apply the ownership rule at every consumer Review of the first commit found places that still did, or predicted, the old behaviour. One rule now decides whether a link is skillshare's: Manifest.OwnsLink (the manifest records a link there, or it points into the source). It compares canonical paths, so a source reached through an alias and a relative project link still count as skillshare's. - copy mode kept re-pointing: it removed any same-name link and wrote a copy. It now keeps a link it does not own, like merge mode. - the dashboard diff predicted a prune for a folder that is only named like skillshare's, and an update for another tool's link. It now reports them as local and kept. The orphan-link prediction uses the same rule as prune. - `diff` reported a target as in sync while sync printed "kept local" for another tool's link. It lists the link as a local override. - doctor reported a broken link skillshare did not create as an error and suggested `skillshare sync`, which now keeps it. It is a warning with its own row, and `broken_symlinks` is `warning` in --json. - `trash restore` put a folder init had replaced into the source as a new nested skill. Restore refuses entries under replaced-by-init/ and names the trash folder to copy from. - init reported a folder it could not move to the trash as one that differs from the source, and dropped the error. It is reported separately, with the error. - the PruneOptions.ManagedOnly comment still said broken external links are skipped; manifest-recorded ones are removed. Tests cover the states the review listed: a source behind an alias, a relative project link, ManagedOnly, standard naming, dry run with --force, and a recorded copy the user replaced with a link. TestSync_Pruning_RemovesBrokenExternalSymlinks passed without testing anything, because FileExists follows links; it is now two tests that use Lstat, one per owner. Agent merge is unchanged: agents have no link manifest. * fix(diff): list another tool's link as kept in copy mode too Copy mode now keeps a same-name link skillshare did not create, but both diffs read the entry with os.Stat. A broken link showed as a skill to add on every run, and a live one as a plain local copy, while sync kept both and said "kept local". `diff` and the dashboard diff check the link first and report it the way merge mode does: a local override, kept until --force. * test(sync): make the aliased-source link while its folder exists TestSyncMergeRepointsUnrecordedLinkIntoAliasedSource failed on Windows: it linked straight to a missing folder, and a junction cannot be made to one. It now links first and removes the folder after, like the other broken-link tests in this file. * fix(sync): compare a broken link by where it would point linksIntoSource resolved both paths with EvalSymlinks, which gives up on a path that does not exist. A broken link is exactly that, so a link into a source reached through an alias (a symlinked config folder, or a short 8.3 path on Windows) compared an unresolved path with a resolved one and was taken for another tool's link. Sync then kept it instead of repairing or pruning it. It now uses sourcewalk.Canonical, which resolves the nearest folder that exists and keeps the missing tail. The test covers both spellings: the alias in the link, and the alias in the configured source. * fix(init): report what the first sync kept, and match prune in the diff Two previews said less, or more, than sync does. init ran its first sync quietly and printed only "Synced". Sync now keeps a link another tool put on a skill's name, a folder that is only named like skillshare's, and a broken link it did not create, so the skill was reported as synced while the tool still loaded the other copy. firstSync returns the warnings a plain sync prints, and init shows them. They already name the folders that differ from the source, so the separate list of those is gone. The dashboard diff counted an orphan link as a removal whenever the manifest recorded it. Prune keeps a recorded link that still resolves outside the source (the source moved and the old checkout stayed), so the Sync page showed a removal that never happened. The diff now uses prune's own rule: a link into the source goes when broken or recorded; any other link only when broken and recorded. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Willie <egg358358@gmail.com>
749 lines
27 KiB
Markdown
749 lines
27 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
---
|
|
|
|
# sync
|
|
|
|
Push skills from source to all targets.
|
|
|
|
Use `skillshare sync hooks` for native hooks (see [hooks](./hooks.md)).
|
|
Use `skillshare sync mcp` for MCP connection settings, or `skillshare sync --all`
|
|
to include skills, agents, extras, MCP and hooks. 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).
|
|
:::
|
|
|
|
## Agent-specific skill variants
|
|
|
|
In a tracked repository, `skills/<known-agent>/<skill-path>/SKILL.md` is recognized as an agent-specific variant only when the same complete skill path exists under at least two distinct canonical agents beneath the same `skills/` parent. Aliases of one agent alone do not qualify. A lone category such as `skills/agents/planner` remains an ordinary skill.
|
|
|
|
In merge/copy mode, variants route to the matching agent, including aliases and account targets. Compatible targets sharing one skills folder select the union of their agent identities: Codex and `universal` sharing `~/.agents/skills` keep the Codex variants. Each reader sees that shared union; incompatible settings still produce overlap/conflict diagnostics. Explicit source-local target overrides and frontmatter routing retain precedence, and ignores and include/exclude filters still apply.
|
|
|
|
Source and repository summaries count logical skills once and show physical variants separately, for example `2 skills, 4 variants`. Per-target sync operations remain physical counts. Whole-directory symlink mode exposes every variant; `status` and `doctor` explain this limitation and recommend merge or copy for automatic routing.
|
|
|
|
## 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).
|
|
|
|
When sync adopts a hand-moved declared skill, only that skill's project entry,
|
|
ignore rule and existing lock pin follow the move. A stale install record alone
|
|
does not change `config.yaml`, `.gitignore` or `skills.lock.json`, and other
|
|
remote installs in the source are not added to the project's `skills:` list.
|
|
|
|
```
|
|
.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 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 + hooks
|
|
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, MCP and hooks 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",
|
|
"warnings": ["source link _dev-skills not followed: target is missing; kept existing target entries, nothing pruned this run"],
|
|
"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.
|
|
|
|
`warnings` appears only when a first-level source link was not followed (see [`follow_source_links`](../targets/configuration.md#follow_source_links)). A run that kept target entries because the link's target was unavailable says so there; `pruned` is `0` in that case by design.
|
|
|
|
### 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
|
|
```
|
|
|
|
### When a target fails {#when-a-target-fails}
|
|
|
|
Sync runs every target; one failed target does not stop the others. A target fails when syncing it hits an error, or when its own settings in the config are invalid, for example its skills path is a file instead of a folder or its `mode` is unknown. A target with invalid settings is skipped for skills and agents in that run. Each failed target is reported (`✗ <target> invalid config: …` in text output, `error` in its `--json` `details` entry), and the command exits non-zero after the other targets have synced.
|
|
|
|
Problems with the config as a whole still stop sync before any target runs: a missing or invalid source folder, an invalid global `mode` or `target_naming`, an invalid `git_root`, or invalid extras.
|
|
|
|
### Example Output
|
|
|
|
```text
|
|
$ skillshare sync
|
|
✓ Backup claude, claude-work, cursor, gemini, opencode, universal → ~/.local/share/skillshare/backups/2026-09-28_12-52-50
|
|
✓ claude 43 linked · 1 pruned
|
|
✓ claude-work 43 linked · 1 pruned
|
|
✓ cursor 43 linked · 1 local · 1 pruned
|
|
✓ gemini 43 linked · 1 pruned
|
|
✓ opencode 43 linked · 1 pruned
|
|
✓ universal 43 linked · 1 pruned
|
|
|
|
✓ Synced 43 skills to 6 targets · 0.0s
|
|
Context ~1.2K tokens always loaded · ~18.5K on demand
|
|
```
|
|
|
|
When a folder you made already sits on the name a skill syncs to, sync keeps your folder and does not install the skill. The same goes for a link another tool put there: one that points outside the source and that the manifest does not record. Each target with such folders gets one line naming the first few (`kept local: a, b (sync --force replaces them)`), and they count as `local` instead of `up to date`. `skillshare diff` lists them as `Local override`.
|
|
|
|
---
|
|
|
|
## 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`)
|
|
- An `include` pattern that matches no skill is reported, because such a target syncs nothing and drops what a previous pattern linked. Filters keep using flat names even when `target_naming: standard` or `prefixed` names the target entry after `SKILL.md`
|
|
- `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
|
|
- Targets that share one folder need the same filters, mode and target naming (filters and naming don't matter when both use `symlink` mode); otherwise each sync undoes the other and `sync` warns (see [`sync` keeps showing the same changes](/docs/troubleshooting/common-errors#sync-keeps-showing-the-same-changes))
|
|
|
|
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:
|
|
- Links skillshare created for source skills that are now filtered out are pruned
|
|
- A live symlink/junction into the source that skillshare never tracked is preserved and counted as local
|
|
- 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 snapshots and abandoned incomplete directories
|
|
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, MCP, and hooks:
|
|
|
|
```bash
|
|
skillshare sync # Sync skills only (default)
|
|
skillshare sync agents # Sync agents only
|
|
skillshare sync --all # Sync skills + agents + extras + MCP + hooks
|
|
```
|
|
|
|
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. In merge mode, orphan cleanup removes only broken links and links that point into the agents source; live links to agent files elsewhere and local files are preserved.
|
|
|
|
---
|
|
|
|
## 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 + hooks
|
|
```
|
|
|
|
| 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. `sync --all` also exits
|
|
non-zero when an extras target fails, with or without `--json`. An extra whose source
|
|
directory does not exist is skipped with a hint, not created. 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, MCP, and hooks 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 broken symlinks and symlinks into the extra's source are pruned — user-created local files and live links to other locations 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
|
|
|
|
Extras
|
|
✓ rules ~/.claude/rules 2 files linked
|
|
✓ rules ~/.cursor/rules 2 files copied
|
|
✓ commands ~/.claude/commands 1 files linked
|
|
|
|
✓ Synced 2 extras to 3 folders · 0.0s
|
|
```
|
|
|
|
---
|
|
|
|
## Context Cost {#context-cost}
|
|
|
|
After syncing, skillshare displays a token cost summary:
|
|
|
|
```
|
|
✓ Synced 47 skills to 4 targets · 0.3s
|
|
Context ~12.4K tokens always loaded · ~58.2K on demand
|
|
```
|
|
|
|
- **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
|