* feat(sync): make prefixed target naming misconfigurations visible Prefixed naming (#497) works, but several of its failure modes only showed up at sync time or gave advice that cannot be followed: - A collision that only prefixing creates told the user to "rename one in SKILL.md", which a tracked skill cannot do, and never said the prefix caused it. The hint now names the prefixing and points at renaming the other skill or re-tracking the repo with --name. - `target add` silently wrote mode: copy when the inherited naming is prefixed. The CLI now says so. - A target that resolves to prefixed outside copy mode was reported only by sync. status, doctor and target list (plain and JSON) now flag it, and the sync/validation and `--skills=true` errors say how to fix it. - The dim "duplicate skill names (isolated by ...)" line printed on every sync even when nothing was wrong, and before a failing sync. Isolated duplicates are not a problem, so it is dropped; the website docs still showed an outdated form of this output and are corrected in all locales. * fix(status): flag prefixed-outside-copy in the TUI list and status --json Codex review of #503 found two surfaces the new check missed: - The interactive `target list` (the default on a terminal) never read the item's naming error, so a prefixed + merge target looked healthy there. The list row now marks the mode with "!" and the detail panel shows the fix. - `status --json` (global and project) builds its target entries directly, so scripts got no signal. Each target now carries a `warning` string, matching `target list --json`. * docs(troubleshooting): sync no longer prints a message for isolated duplicates The collision troubleshooting tip still said sync shows an info message when filters isolate duplicate skill names. That line was dropped, so the tip now says sync prints nothing about them. Codex review of #503 flagged the stale English page and its four translations. * fix(config): point managed-project naming errors at the project settings The "set mode: copy on the target" hint is wrong for a target a global `projects:` entry expands into: it cannot be edited with `target` or under `targets:`, and the mode lives in the project's skills settings. The hint now depends on whether the target belongs to a managed project (Codex review of #503). The naming/mode check becomes a TargetConfig method so status, doctor and target list share it, which also lets the hint see the project root. Along the way: doctor reuses it, the TUI list renders the mode once, and reportTargetAdded takes a flag instead of comparing a mode string. * fix(config): hint the project settings for managed-project naming errors ProjectNamingError (the config-load check for a global `projects:` entry) still returned the bare naming error, so a project that inherits prefixed with a non-copy mode got no fix. It now names the project's skills settings, like the expanded targets do. The built-in skill's sync reference also mentions that status, doctor and target list flag the misconfiguration before sync. Found by the second /code-review pass on #503. * fix(sync): detect prefix collisions from the colliding paths reportCollisions decided a collision came from prefixing when its name was not also a duplicate in the source. A tracked skill that joined two ordinary skills already sharing the name was therefore sent to the "rename one in SKILL.md" hint, which a tracked skill cannot follow (Codex review of #503). A collision on a prefixed target that includes a tracked path now gets the tracked-skill hint, whatever else shares the name. The wording no longer claims prefixing renamed the skill, since a name that already starts with the repo name is unchanged. * fix(sync): use discovered repo metadata for the tracked-skill hint The collision hint treated any path segment starting with "_" as a tracked repo, so an ordinary skill under a folder such as org/_drafts (no .git) was told it could not be renamed and to re-track a repo that does not exist. It now uses DiscoveredSkill.IsInRepo, the same signal prefixed naming uses. The prefixed docs also gain the fix for a target a global `projects:` entry expands into (projects.<root>.skills.mode: copy), since `target` cannot edit those. Both from Codex review of #503. * fix(sync): keep both collision hints when targets disagree The same name can clash on a prefixed target with a tracked skill and on another target between ordinary skills only. The prefixed flag was OR-ed across targets, so the second case lost its rename/filter hint. Track both kinds separately while grouping, and print each hint that applies (Codex review of #503). * fix(sync): keep the rename hint inside a mixed collision group When a tracked skill and two ordinary skills share a prefixed name, re-tracking the repo fixes only the tracked one; the ordinary pair still clashes and is excluded. The group now also shows the rename/filter hint when at least two of its participants are not tracked (Codex review of #503). * fix(sync): offer filters in the tracked-skill collision hint Two tracked skills of the same repo with the same name collide after prefixing, and neither renaming a tracked skill nor re-tracking the repo separates them. The hint now also names include/exclude filters, so every collision on a prefixed target has an actionable remedy (Codex review of #503). * docs(sync-modes): limit the target list claim to targets under targets target list builds from the config without project expansion, so it cannot flag a target a `projects:` entry expands into; status and doctor can. The prefixed paragraph and the built-in skill reference said all three flag it (Codex review of #503).
15 KiB
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)
:::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:
includekeeps matching namesexcluderemoves from that kept set
Quick choices:
- Use
includewhen the target should get only a small subset - Use
excludewhen the target should get almost everything - Use
include + excludewhen 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
syncrebuilds it
Symlink Mode
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
By-target overrides (recommended)
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, 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-uxstaysbmad-ux. - Skills outside tracked repos keep their name.
- The source skill must pass the
standardchecks first. A prefixed name longer than 64 characters is skipped with a warning, and names that still collide are skipped as instandard. A tracked skill cannot be renamed inSKILL.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 mpgivesmp-prototype. - Relative links to sibling skills (
../other-skill/) are not rewritten, the same asflatin 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.
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 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
- sync — Run sync to apply mode changes
- target — Change a target's sync mode
- Source & Targets — The core architecture
- Configuration — Per-target settings