Files
skillshare/docs/sync.md
T
Willie Hung 08de85e390 docs: restructure README and add comprehensive docs/
- Slim README from 777 to 214 lines for better readability
- Adjust value prop: emphasize sync, bidirectional, team over AI-native
- Split detailed content into docs/ directory:
  - install.md: init, install, update, upgrade, uninstall
  - sync.md: sync, pull, push, backup, restore with diagrams
  - targets.md: target management with flowcharts
  - cross-machine.md: multi-machine sync setup
  - team-edition.md: tracked repos, nested skills, team sharing
  - configuration.md: config file reference
  - faq.md: doctor command, FAQ, troubleshooting
- Add docs/README.md as documentation index
- Remove /docs/ from .gitignore
2026-01-20 22:50:52 +08:00

18 KiB

Sync, Pull, Push & Backup

Overview

┌─────────────────────────────────────────────────────────────────┐
│                      SYNC OPERATIONS                            │
│                                                                 │
│                        ┌──────────┐                             │
│                        │  Remote  │                             │
│                        │  (git)   │                             │
│                        └────┬─────┘                             │
│                    push ↑   │   ↓ pull --remote                 │
│                             │                                   │
│    ┌────────────────────────┼────────────────────────┐          │
│    │                  SOURCE                         │          │
│    │        ~/.config/skillshare/skills/             │          │
│    └────────────────────────┬────────────────────────┘          │
│                 sync ↓      │      ↑ pull <target>              │
│         ┌───────────────────┼───────────────────┐               │
│         ▼                   ▼                   ▼               │
│   ┌──────────┐        ┌──────────┐        ┌──────────┐          │
│   │  Claude  │        │  Cursor  │        │  Codex   │          │
│   └──────────┘        └──────────┘        └──────────┘          │
│                         TARGETS                                 │
└─────────────────────────────────────────────────────────────────┘
Command Direction Description
sync Source → Targets Push skills to all targets
pull <target> Target → Source Pull skills from one target
push Source → Remote Commit and push to git
pull --remote Remote → Source → Targets Pull from git, then sync

Sync

Push skills from source to all targets.

skillshare sync              # Sync to all targets
skillshare sync --dry-run    # Preview changes
skillshare sync -n           # Short form

What Happens

┌─────────────────────────────────────────────────────────────────┐
│ skillshare sync                                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. Backup targets (automatic)                                   │
│    → ~/.config/skillshare/backups/2026-01-20_15-30-00/          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. For each target:                                             │
│    ┌─────────────────────────────────────────────────────────┐  │
│    │ merge mode:                                             │  │
│    │   • Create symlink for each skill                       │  │
│    │   • Preserve local-only skills                          │  │
│    │   • Prune orphaned symlinks                             │  │
│    ├─────────────────────────────────────────────────────────┤  │
│    │ symlink mode:                                           │  │
│    │   • Replace entire directory with symlink               │  │
│    └─────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Report results                                               │
│    ✓ claude: merged (5 linked, 2 local, 0 updated, 1 pruned)    │
│    ✓ cursor: merged (5 linked, 0 local, 0 updated, 0 pruned)    │
└─────────────────────────────────────────────────────────────────┘

Example Output

$ skillshare sync

Syncing skills
─────────────────────────────────────────
→ Source: ~/.config/skillshare/skills (5 skills)

✓ claude: merged (5 linked, 2 local, 0 updated, 1 pruned)
✓ cursor: merged (5 linked, 0 local, 0 updated, 0 pruned)
✓ codex: symlink

Sync complete

Status

Show current sync state.

skillshare status

Example Output

Skillshare Status
─────────────────────────────────────────
Source: ~/.config/skillshare/skills
  Skills: 5
  Git: clean (remote: origin)

Targets:
  claude    merge     5/5 synced    ~/.claude/skills
  cursor    merge     5/5 synced    ~/.cursor/skills
  codex     symlink   ✓ linked      ~/.codex/skills

Tracked Repositories:
  _team-repo    5 skills    up-to-date

Diff

Show differences between source and targets.

skillshare diff              # All targets
skillshare diff claude       # Specific target

Example Output

Diff: source ↔ claude
─────────────────────────────────────────
  + my-new-skill      (in source, not in target)
  - old-skill         (in target, not in source)
  ~ modified-skill    (different content)

Pull

Pull skills from a target back to source.

Pull from Target

skillshare pull claude           # Pull from Claude
skillshare pull claude --dry-run # Preview
skillshare pull --all            # Pull from all targets

When to use: You created/edited a skill directly in a target (e.g., ~/.claude/skills/) and want to bring it to source.

┌─────────────────────────────────────────────────────────────────┐
│ skillshare pull claude                                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. Find skills in target that aren't symlinks                   │
│    → ~/.claude/skills/new-skill/ (local)                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Copy to source                                               │
│    → ~/.config/skillshare/skills/new-skill/                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Replace original with symlink                                │
│    ~/.claude/skills/new-skill → source/new-skill                │
└─────────────────────────────────────────────────────────────────┘

After pulling:

skillshare pull claude
skillshare sync  # ← Distribute to other targets

Pull from Remote

skillshare pull --remote     # Pull from git remote

When to use: You pushed changes from another machine and want to sync them here.

┌─────────────────────────────────────────────────────────────────┐
│ skillshare pull --remote                                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. cd ~/.config/skillshare/skills                               │
│    git pull                                                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. skillshare sync (automatic)                                  │
└─────────────────────────────────────────────────────────────────┘

Push

Commit and push source to git remote.

skillshare push                  # Auto-generated message
skillshare push -m "Add pdf"     # Custom message
┌─────────────────────────────────────────────────────────────────┐
│ skillshare push -m "Add pdf skill"                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ cd ~/.config/skillshare/skills                                  │
│ git add .                                                       │
│ git commit -m "Add pdf skill"                                   │
│ git push                                                        │
└─────────────────────────────────────────────────────────────────┘

Conflict handling:

  • If remote is ahead, push fails → run pull --remote first

Sync Modes

Mode Behavior Use case
merge Each skill symlinked individually Default. Preserves local skills.
symlink Entire directory is one symlink Exact copies everywhere.

Merge Mode (Default)

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/                         ~/.claude/skills/
├── my-skill/        ────────►  ├── my-skill/ → (symlink)
├── another/         ────────►  ├── another/  → (symlink)
└── ...                         ├── local-only/  (preserved)
                                └── ...
Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/              ────────►  ~/.claude/skills → (symlink to source)
├── my-skill/
├── another/
└── ...

Change Mode

skillshare target claude --mode merge
skillshare target claude --mode symlink
skillshare sync  # Apply change

Safety 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

Backup

Backups are created automatically before sync and target remove.

Location: ~/.config/skillshare/backups/<timestamp>/

Manual Backup

skillshare backup              # Backup all targets
skillshare backup claude       # Backup specific target
skillshare backup --list       # List all backups
skillshare backup --cleanup    # Remove old backups
skillshare backup --dry-run    # Preview

Example Output

$ skillshare backup --list

Backups
─────────────────────────────────────────
  2026-01-20_15-30-00/
    claude/    5 skills, 2.1 MB
    cursor/    5 skills, 2.1 MB
  2026-01-19_10-00-00/
    claude/    4 skills, 1.8 MB

Restore

Restore targets from backup.

skillshare restore claude                              # Latest backup
skillshare restore claude --from 2026-01-19_10-00-00   # Specific backup
skillshare restore claude --dry-run                    # Preview
┌─────────────────────────────────────────────────────────────────┐
│ skillshare restore claude                                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. Find latest backup for claude                                │
│    → backups/2026-01-20_15-30-00/claude/                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Remove current target directory                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Copy backup to target                                        │
│    → ~/.claude/skills/                                          │
└─────────────────────────────────────────────────────────────────┘