Files
skillshare/website/docs/reference/commands/diff.md
T
Willie 2ff8bdeb59 fix(diff): report a copy recorded under another naming as modified
Sync re-copies a managed copy whose recorded naming differs from the
current one, for example after a migration stopped between the rename
and the re-copy. Diff skipped it on the mtime fast path and reported the
target in sync while its SKILL.md kept the old name. Check the recorded
naming first in both the CLI and the dashboard diff.
2026-10-09 12:10:08 +08:00

6.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 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": "link", "name": "missing-skill", "reason": "not in target", "is_sync": true},
        {"action": "update", "name": "local-copy", "reason": "local override", "is_sync": true}
      ],
      "include": [],
      "exclude": []
    }
  ],
  "duration": "0.045s"
}

See Also