Files
skillshare/website/docs/reference/commands/diff.md
T
Willie ec2a8ab3aa fix(sync): close gaps found while simulating the prefixed naming switch (#504)
* fix(sync): close gaps found while simulating the prefixed naming switch

Simulating the #497 reporter's switch from merge + flat to copy + prefixed
turned up four problems:

- `target X --mode copy --target-naming prefixed` applied only --mode, since
  the setter dispatch returned after the first flag. Both flags given
  together now check the final pair, then apply in an order that keeps the
  saved pair valid (copy mode first, any other mode last).
- Skipped skills were only counted, so a prefixed name over 64 characters
  vanished with "1 skill(s) skipped". Sync now names the first five with
  their reason; the cap keeps huge sources from flooding the output.
- In copy mode a merge-mode link to the skill was not a managed entry, so
  when a local folder held the new name the old link was pruned and the
  skill left the target, contrary to the documented "old managed entry is
  preserved". Copy mode now migrates such links like managed copies.
- PATCH /api/targets validated the mode/naming pair against the current
  skills state, so disabling skills while changing mode was rejected. It now
  checks the state the request leaves the target in.

* docs(target): drop stray space in the Japanese mode+naming sentence

* fix(diff): save paired target settings once and report kept legacy entries

- `target X --mode M --target-naming N` ran the two setters, each saving
  the config, so a failed second save left half the change behind (Codex
  on #504). Both fields are now set and saved once, after the final pair
  is checked.
- When a local folder holds the name a skill's naming now gives it, sync
  keeps the skill under its old entry and leaves the folder alone, even
  with --force. diff still called the folder a "local copy" and suggested
  `sync --force`, which does nothing for it. CLI and Web API diff, copy
  and merge mode, now report the folder and the entry the skill stays at.

* fix(sync): migrate only links the manifest records as merge-made

Copy mode treated any link to the skill's source at an old naming's name as
the entry merge mode left behind, so a user's own link was renamed and
replaced with a copy (Codex on #504). A link now migrates only when the
manifest records it as "symlink", which merge mode writes for links it makes;
other links stay as the user left them. The value is now a named constant.

* fix(diff): mark kept legacy entries as unaffected by force

Two problems Codex found on #504:

- The Web API diff sent a local folder on a skill's new name as a "skip",
  which the dashboard shows as an edited entry that Force replaces. Sync
  keeps that folder and the legacy entry even with force, so the preview
  promised a change that never happens. It is now its own "kept" action,
  shown with its reason and not counted.
- `target X --mode M --target-naming N` printed the target's own naming as
  the old value, so a target inheriting standard or prefixed showed
  "flat -> ...". It now prints the naming the target had in effect.

* fix(diff): keep kept-name conflicts out of the sync count

Two problems Codex found on #504:

- A local folder on a skill's new name counted toward "N to sync" and
  fell through to the plain `skillshare sync` hint, though sync changes
  nothing there until the folder is renamed or removed. Such rows now
  carry a kept flag, count as neither sync nor local, and print their own
  hint; a target whose only row is kept still shows that row.
- The dashboard grouped targets by row name and icon only, so two targets
  keeping the same skill at different old entries merged and showed one
  target's old location for both. The row detail is now part of the key.

* fix(diff): do not list a kept local folder's files as deletions

A kept row (a local folder on a skill's new name) still pointed at that
folder, so `diff --stat` and `--patch` listed each of its files as removed,
though sync never touches the folder (Codex on #504). Kept rows no longer
point at a target directory, so no file-level diff is built for them in the
CLI or the TUI.

* fix(diff): report kept skills consistently in every diff view

An exhaustive review of the kept-row change (prompted by two Codex findings
on #504) found the same gap in several places:

- A target whose only rows were kept was summarized as "in sync", and mixed
  summaries left it out of every count. Such targets now count as "N kept
  under old name" with a warning mark, and the scan progress counts them.
- Plain output and the TUI hid where the skill stays; rows now read
  "name (stays at old-name)". The TUI also lacked the kept Next hint and
  called kept-only targets "differs"; it now matches the plain output.
- `diff --json` emitted kept rows as "remove", indistinguishable from
  local-only folders; it now emits "kept", as the Web API does. The diff
  docs' JSON example also showed actions the CLI never emits.
- Renamed rows whose old entry is a merge-made link showed a bogus file
  stat, because the link was walked as a file; a link now stands for the
  folder it points to.
- A dry-run migration printed "Would copy" to the old path; it now names
  the new one.

* fix(sync): stop reporting kept folders and skipped skills as pending work (#509)

Three reports told users to do something sync cannot do, or hid what it
did:

- Copy and merge sync kept a folder the user made on a skill's name but
  counted it as "up to date" with no hint. Sync now counts it as local and
  adds one capped line per target naming the folders and saying that
  `sync --force` replaces them. The line is added in SyncSkillTarget, so
  the dashboard gets it too.
- status and doctor counted skills that sync skips on purpose (invalid
  names under standard or prefixed naming, name collisions) as "not
  synced — run skillshare sync". Running sync can never add them, so the
  advice looped. They now compare against the skills sync places.
- diff marked a target whose only items were local-only folders as "to
  sync" and `synced: false`. Those items are still listed, but they no
  longer make the target pending.

* fix(target): apply every setting flag, require flag values, report no-ops as unchanged (#507)

* fix(target): apply every setting flag, require flag values, report no-ops as unchanged

`skillshare target <name>` dispatched --mode, --agent-mode and
--target-naming through an if-chain that returned after the first match,
so `--agent-mode copy --target-naming prefixed` applied one setting and
silently dropped the other. Filters, --skills and --dry-run had the same
early-return problem.

- Check --mode, --agent-mode and --target-naming as a whole and save
  once, in global and project mode (one targetSettingsUpdate replaces six
  per-flag functions).
- Reject --mode/--agent-mode/--target-naming combined with filters or
  --skills, and --dry-run without --skills, instead of dropping them.
- A value flag followed by another flag (or an empty string) now reports
  "<flag> requires a value"; `--target-naming -p` used to report an
  invalid naming '-p'.
- A value the target already has is reported as unchanged and the config
  is not rewritten.

* fix(target): leave the skills pair alone on agents-only changes

A target with skills off may keep target_naming prefixed with a merge
mode it cannot sync; validateGlobalTarget and validateProjectTarget only
check that pair for enabled skills. The combined settings update ran the
pair check for every setting, so `target claude --agent-mode copy` was
refused on such a target although the old agent-mode handler never looked
at skills settings. Check the pair only when --mode or --target-naming is
given.

* docs(target): show combined settings in --help and the built-in skill

The combined --mode/--agent-mode/--target-naming form is now the way to
move a target to copy + prefixed in one step, but neither the help
examples nor the built-in skill's target reference showed it.
2026-10-09 23:59:47 +08:00

7.3 KiB

sidebar_position
sidebar_position
2

diff

Show differences between source and targets.

skillshare diff              # All targets (interactive TUI)
skillshare diff claude       # Specific target
skillshare diff agents       # Agent targets only
skillshare diff --stat       # File-level changes
skillshare diff --patch      # Full unified diff
skillshare diff --no-tui

claude, claude-work, gemini, opencode, universal
  New       remotion-captions

cursor
  Local only  cursor-shortcuts
  New         remotion-captions

Extras
✓ commands  ~/.claude/commands · in sync
✓ rules     ~/.claude/rules · in sync
✓ rules     ~/.cursor/rules · in sync
✓ team      ~/.codex · in sync
✓ team      ~/.claude · in sync
✓ team      ~/.gemini · in sync
✓ team      ~/notes · in sync

! 6 targets: 6 to sync

Next
  skillshare sync     apply the changes
  skillshare collect  copy local-only skills into source

Interactive TUI

On a TTY, diff opens an interactive view: targets on the left, and what differs for the selected target on the right, down to file-level diffs. The keys are listed at the bottom of the screen. Use --no-tui, or pipe the output, for plain text.

When to Use

  • See exactly what's different between source and a target before syncing
  • Find skills that exist only in a target (local-only, not yet collected)
  • Identify local copies that could be replaced by symlinks
  • Inspect file-level changes with --stat or full text diff with --patch

Example Output

claude
  Local override  local-copy
  Local only      my-local-skill
  New             another-skill, missing-skill

✓ cursor    in sync

! 2 targets: 1 to sync, 1 in sync

Next
  skillshare sync          apply the changes
  skillshare sync --force  also replace local copies
  skillshare collect       copy local-only skills into source

Grouped Multi-Target Output

When multiple targets have identical diff results, they are grouped into a single block to reduce noise:

agents, claude
  New       skill-1, skill-2

cursor
  New       skill-1

✓ codex, copilot  in sync

Targets with different results (e.g. due to include/exclude filters) are still shown separately.

Labels

Label Meaning Action
New In source, missing in target sync will add it
Restore Was in target, deleted sync will restore it
Modified Content or target naming changed (copy mode) sync will update it
Renamed Managed entry still under the name an earlier target_naming gave it sync will rename it
Local only, skill kept under old name A local folder holds the name the current target_naming gives a skill, so the skill stays under its old managed entry, shown as name (stays at old-name) Rename or remove the folder, then sync
Local override Local copy instead of symlink sync --force to replace
Orphan In manifest but not in source sync will prune it
Local only Only in target, not in source collect to import

File-Level Details

--stat

Shows which files differ within each skill:

skillshare diff --stat
claude
  Modified  my-skill
            + new-file.md (120 bytes)
            ~ SKILL.md (840 → 912 bytes)
            - old-file.md (64 bytes)

--patch

Shows full unified text diff for modified files:

skillshare diff --patch
claude
  Modified  my-skill
            ~ SKILL.md (840 → 912 bytes)
            --- SKILL.md
            - old line
            + new line

Both --stat and --patch imply --no-tui (plain text output).

What Diff Shows

Merge Mode Targets

For targets using merge mode (default):

  • Lists skills in source not yet symlinked to target
  • Shows skills that exist as local copies instead of symlinks
  • Identifies local-only skills in target (not in source — preserved by sync)

Copy Mode Targets

For targets using copy mode:

  • Lists skills in source not yet managed (missing from manifest)
  • Shows content changes via checksum comparison
  • Shows orphan managed copies no longer in source (will be pruned on sync)
  • Identifies local-only skills (not in source and not managed)

For targets using symlink mode:

  • Simply checks if symlink points to correct source
  • Shows "in sync" or warns about wrong symlink

Use Cases

Before Sync

Check what will change:

skillshare diff
# See what sync will do, then:
skillshare sync

Finding Local Skills

Discover skills you created directly in a target:

skillshare diff claude
# Shows: Local only  my-local-skill

skillshare collect claude  # Import to source

Inspecting Changes

See exactly what changed in a skill before syncing:

skillshare diff --patch claude   # Full text diff
skillshare diff --stat claude    # File-level summary

Troubleshooting

When sync status shows issues:

skillshare status          # Shows "needs sync"
skillshare diff claude     # See exactly what's different
skillshare sync            # Fix it

Agent Diff

Use the agents keyword to diff only agent targets:

skillshare diff agents             # All agent-capable targets
skillshare diff agents claude      # Specific target
skillshare diff agents --json      # JSON output

Agent diff shows missing agents (need sync), orphan symlinks (need prune), and local-only agent files. Only targets with an agents path configuration are included. See Agents — Supported Targets for the full list.


Options

Flag Description
--project, -p Use project mode
--global, -g Use global mode
--stat Show file-level changes (implies --no-tui)
--patch Show full unified diff (implies --no-tui)
--no-tui Plain text output (skip interactive TUI)
--json Output as JSON (implies --no-tui)

JSON Output

skillshare diff --json
{
  "targets": [
    {
      "name": "claude",
      "mode": "merge",
      "synced": false,
      "items": [
        {"action": "add", "name": "missing-skill", "kind": "skill", "reason": "source only", "is_sync": true},
        {"action": "modify", "name": "local-copy", "kind": "skill", "reason": "local copy (sync --force to replace)", "is_sync": true},
        {"action": "remove", "name": "my-own-skill", "kind": "skill", "reason": "local only", "is_sync": false},
        {"action": "kept", "name": "prototype", "kind": "skill", "reason": "local folder; the skill stays at _emil-design__skills__prototype", "is_sync": false}
      ],
      "include": [],
      "exclude": []
    }
  ],
  "duration": "0.045s"
}

synced is true when sync has nothing to do for the target. Items with "is_sync": false, such as folders that exist only in the target, are still listed but do not make it false. The text output likewise counts a target with only local-only folders as in sync.

action is add, modify, remove, or kept. kept means a local folder holds the name the current target_naming gives the skill, so the skill stays under its old name and sync leaves the folder alone.

See Also