Files
1419b62499 fix(sync): never delete or re-point entries skillshare did not create (#914)
* 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>
2026-11-17 04:15:04 +08:00

16 KiB
Raw Permalink Blame History

sidebar_position
sidebar_position
3

Sync Modes

How skillshare links source to targets.

:::tip When does this matter? Choose merge mode (default) when you want per-skill symlinks and to preserve local skills in targets. Choose copy mode when you need real files instead of symlinks (portability, CI, or personal preference). Choose symlink mode when you want the entire directory linked and don't need local target skills. :::

Overview

Mode Behavior Use Case
merge Each skill symlinked individually Default. Preserves local skills.
copy Each skill copied as real files Portability, CI/sandboxed environments, or when you prefer real files over symlinks.
symlink Entire directory is one symlink Exact copies everywhere.

Decision Matrix (Neutral)

Use this table to pick based on your constraints, not target brand names:

Decision axis merge copy symlink
Compatibility across different AI CLIs Medium High Low–Medium
Edit-once immediate reflection High Low (requires sync) High
Disk usage Low High Low
Safety against accidental delete-from-target High High Low
Operational simplicity Medium Medium High
Per-target filtering (include/exclude) Yes Yes No

If you are unsure, start with merge and switch specific targets to copy as needed.


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)
                                └── .skillshare-manifest.json

Advantages:

  • Keep target-specific skills (not synced)
  • Mix installed and local skills
  • Granular control
  • Per-target include/exclude filtering
  • Manifest-based orphan cleanup (safely removes non-symlink residue after uninstall)
  • Links that other tools put in the target are left alone: a same-name link that points outside the source and is not in the manifest is kept and reported as local (sync --force replaces it). Copy mode keeps such a link too

:::info Relative symlinks in project mode In project mode (-p), symlinks are created as relative paths (e.g., ../../.skillshare/skills/my-skill) instead of absolute paths. This makes the project portable — move or rename the directory and symlinks continue to work. In global mode, absolute paths are used since source and targets are in different locations. :::

When to use:

  • You want some skills only in specific AI CLIs
  • You want to try local skills before syncing
  • You want one source but different skill subsets per target

Filter strategy in merge mode

include and exclude are evaluated per target in this order:

  1. include keeps matching names
  2. exclude removes from that kept set

Quick choices:

  • Use include when the target should get only a small subset
  • Use exclude when the target should get almost everything
  • Use include + exclude when you need a broad subset with explicit carve-outs

Behavior when rules change:

  • Previously synced source-linked entries that become filtered out are removed on next sync
  • Existing local non-symlink folders in target are preserved

See Target Configuration for full examples.


Copy Mode

Each skill is copied as real files to the target directory. A .skillshare-manifest.json file tracks which skills are managed and their checksums, so local skills are preserved.

Source                          Target (cursor)
─────────────────────────────────────────────────────────────
skills/                         ~/.cursor/skills/
├── my-skill/        ────copy►  ├── my-skill/    (real files)
├── another/         ────copy►  ├── another/     (real files)
└── ...                         ├── local-only/  (preserved)
                                └── .skillshare-manifest.json

Why copy mode?

Even when your AI CLI handles symlinks correctly, copy mode provides value:

  • Defensive design — not every AI CLI guarantees symlink support, especially on Windows where symlink behavior varies by platform and permission level
  • Sandboxed environments — strict CI pipelines, containers, and air-gapped setups may not follow symlinks across filesystem boundaries
  • User preference — some users and teams simply prefer real files over symlinks for transparency and portability

Advantages:

  • Works everywhere — no symlink support required from the AI CLI or OS
  • Preserves local skills (same as merge mode)
  • Per-target include/exclude filtering
  • Checksum-based skip: unchanged skills are not re-copied

When to use:

  • Your AI CLI reports "skill not found" or cannot read symlinked skills
  • You want to vendor skills into a project repo — copy mode in project mode lets the team commit real skill files to git, so teammates don't need skillshare installed
  • You need self-contained skill directories that work without a central source (portable setups, CI pipelines, air-gapped environments)
  • You want the same filtering behavior as merge mode but with real files
  • Common first candidates for copy: cursor, antigravity, copilot, opencode

How updates work

On each skillshare sync, the checksum of each source skill is compared to the value stored in the manifest:

  • Same checksum → skill is skipped (fast)
  • Different checksum → skill is overwritten with the new version
  • --force → all managed skills are overwritten regardless of checksum

Manifest lifecycle

Both merge and copy modes write .skillshare-manifest.json to track managed skills:

  • Merge mode: records skill names with value "symlink" — used to safely prune orphan real directories (e.g., copy-mode residue) after uninstall
  • Copy mode: records skill names with SHA-256 checksums — used for incremental sync and orphan detection
  • Removed automatically when switching to symlink mode
  • If manually deleted, the next sync rebuilds it

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 copy mode (for AI CLIs that can't read symlinks)
skillshare target cursor --mode copy
skillshare sync

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

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

Unedited copies that copy mode made are replaced with links on that sync, without --force. Everything else is kept until you run sync --force: a folder you made yourself (the manifest does not record it) and a copy you edited after copy mode made it. A copy whose name: copy mode rewrote for prefixed naming also counts as edited. If the same sync also changes target_naming, a copy gets a new entry name and is removed as an orphan, edited or not; the backup of a plain sync holds it.

You do not need one global mode for every target. A common pattern is:

mode: merge
targets:
  claude:
    path: ~/.claude/skills
    # inherits merge
  cursor:
    path: ~/.cursor/skills
    mode: copy
  codex:
    path: ~/.codex/skills
    mode: symlink

Use per-target overrides when one target needs compatibility-first behavior (copy) while others keep instant reflection (merge/symlink).

Default mode

Set in config for new targets:

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

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

  cursor:
    path: ~/.cursor/skills
    mode: copy  # real files for Cursor

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

Target Naming

Controls how skill directories are named in targets when using merge or copy mode.

Naming Behavior
flat (default) Nested skills flattened with __ separators: frontend/dev → frontend__dev
standard Uses the SKILL.md name field: frontend/dev → dev
prefixed Copy mode only. standard rules, except that name: need not match the folder, plus the tracked repo name in front: _mattpocock-skills/skills/prototype → mattpocock-skills-prototype

Set globally or per-target:

target_naming: standard    # global default
targets:
  claude:
    skills:
      target_naming: flat  # per-target override

Or via CLI:

skillshare target claude --target-naming standard
skillshare sync

Standard mode follows the Agent Skills specification, which requires the SKILL.md name field to match the parent directory name. A valid name has at most 64 lowercase letters (in any script), digits and single hyphens, and does not start or end with -; underscores are not allowed. Skills with invalid names or name collisions are warned and skipped.

Prefixed mode is for tracked repos that ship skills with the same name. Under standard two prototype skills from different repos collide and both are skipped; under prefixed each skill inside a tracked repo becomes <repo>-<name>, so both reach the tool. <repo> is the tracked repo folder without its leading _, lowercased, with every character other than a letter or digit (in any script) turned into -. The prefixed name is used for the folder and written to name: in the copied SKILL.md; the source is never changed.

  • A name that already starts with the repo name is not prefixed again: _bmad/skills/bmad-ux stays bmad-ux.
  • Skills outside tracked repos keep their name.
  • The source skill's name: must follow the standard naming rules, but it does not have to match its folder, since the copy's name: is rewritten: a tracked repo that is itself a skill (_ooux with name: ooux) syncs as ooux. Sync lists the skills named this way. A prefixed name longer than 64 characters is skipped with a warning, and names that still collide are skipped as in standard. A tracked skill cannot be renamed in SKILL.md, so sync then suggests renaming the other skill or re-tracking the repo with --name.
  • For a shorter prefix, track the repo under a short name: skillshare install <repo> --track --name mp gives mp-prototype.
  • Relative links to sibling skills (../other-skill/) are not rewritten, the same as flat in copy mode.
  • The name becomes what the tool shows; in Claude Code it is the slash command, e.g. /mattpocock-skills-prototype.

prefixed needs copy mode because merge links point at the source, where name: cannot change. A target that resolves to prefixed in merge or symlink mode fails validation and is skipped by sync. When a new target would inherit prefixed in a mode other than copy (a project target defaults to merge), target add gives it copy mode. target add says so when it does, and status and doctor flag a target that resolves to prefixed without copy mode before you sync, and so does target list for the targets in targets:; the fix is mode: copy on the target, or projects.<root>.skills.mode: copy for a target a projects: entry expands into.

targets:
  universal:
    skills:
      mode: copy
      target_naming: prefixed

Migration: Switching between flat, standard and prefixed renames existing managed entries in place. In copy mode the manifest records which naming made each copy, so a renamed copy is copied again and its name: matches the new naming, even when the source did not change. If a local skill already occupies the new name, the old managed entry is preserved. When you switch away from prefixed, a skill whose name: differs from its folder is copied again under its new name and its old copy is removed.

Symlink mode: flat and standard are ignored — the entire directory is linked as-is. prefixed fails validation, as above.


Mode Comparison

Aspect Merge Copy Symlink
Local skills preserved ✅ Yes ✅ Yes ❌ No
Symlink-compatible ✅ Yes ❌ Real files ✅ Yes
All targets identical ❌ Can differ ❌ Can differ ✅ Yes
Per-target include/exclude ✅ Yes ✅ Yes ❌ Ignored
Orphan cleanup needed ✅ Yes ✅ Yes ❌ No
Delete safety ✅ Safe ✅ Safe ⚠️ Caution
Disk usage Low (symlinks) Higher (copies) Low (symlinks)

Orphan Cleanup

In both merge and copy modes, sync automatically prunes orphans:

  • Symlinks pointing to deleted source skills are always removed
  • Real directories are removed if they appear in .skillshare-manifest.json (previously managed by skillshare)
  • Unknown directories not in the manifest are preserved with a warning (assumed to be user-created). This includes folders whose names only look like skillshare's (_repo, group__skill); sync --force removes those
  • Broken links pointing outside the source are removed only when the manifest records them (for example, after the source moved); a broken link that another tool or you made is kept with a warning

This means that after uninstall + sync, even non-symlink residue (e.g., directories left from a previous copy mode) is safely cleaned up.

$ skillshare sync
✓ claude    5 linked · 2 local · 1 pruned
✓ cursor    3 copied · 2 up to date · 1 pruned

:::info Agents follow the same modes All three modes (merge, copy, symlink) apply to agent sync as well. Agent orphan cleanup, per-target include/exclude filtering, and mode conversion behave identically to skills — the only difference is that agents are single .md files instead of directories. Agent-capable targets (Claude, Cursor, Augment, OpenCode) honor the same mode setting on their agents: sub-key. See Agents for details. :::


Extras Sync Modes

Extras (non-skill resources like rules, commands, prompts) also use merge and copy modes. Each extras target can specify its own mode:

extras:
  - name: rules
    targets:
      - path: ~/.claude/rules          # merge (default): per-file symlinks
      - path: ~/.cursor/rules
        mode: copy                     # copy: real file copies

The behavior is the same as skill sync modes — merge creates per-file symlinks, copy creates real file copies.

:::note Windows without Developer Mode Merge mode links single files, which Windows allows only with Developer Mode. Without it, agents and extras in merge mode are copied instead, and those copies are updated and pruned like links. Skills are folders, so they are linked (with junctions) either way. See Windows troubleshooting.

Identical local files that skillshare does not own are preserved. In copy fallback, agent counts show them separately as local preserved, for example 0/1 linked, 1 local preserved. :::


See Also