Files
skillshare/website/docs/reference/commands/diff.md
T
Willie 7af9224896 fix(diff): list only what sync prunes, and have doctor follow it (#942)
Three previews disagreed with what sync does to a link no skill or
agent maps to.

The agent diff, in the CLI and the dashboard, listed every orphan link
as a removal. Agent sync prunes a link only in merge mode, and only when
it is broken or points into the source, so a live link to another
location was listed forever. Both diffs now ask the function prune uses.

The CLI diff listed no orphan links at all for merge-mode skills, so a
skill removed from the source showed nothing until sync pruned its
link. It now lists the links sync.OrphanLink says prune removes.

doctor called a broken link "did not create, kept" whenever OwnsLink was
false. Prune also removes a broken link under a name the manifest
records in any form once no skill maps to it, so doctor told the user to
delete by hand a link that sync removes. It now reports those as broken
and suggests sync. An empty source counts as "every entry is an orphan";
only a failed discovery turns the check off.

Closes #939
Closes #940
Closes #941
2026-11-17 13:38:31 +08:00

7.8 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

Ambiguous agent variants appear as (skill selection) skip rows with a diagnostic. Use include/exclude or a source-local target override to select the desired variant. These rows explain skipped selection; they are not changes that sync can apply.

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), or an unedited copy-mode copy that merge sync replaces with a link 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 (including a copy-mode copy you edited) 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)
  • Shows links to skills no longer in source (will be pruned on 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 that sync will 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