Files
skillshare/docs/cross-machine.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

11 KiB

Cross-Machine Sync

Sync your skills across multiple computers using git.

Overview

┌──────────────────────────────────────────────────────────────┐
│                    CROSS-MACHINE SYNC                        │
│                                                              │
│  ┌─────────────────┐                    ┌─────────────────┐  │
│  │   Machine A     │                    │   Machine B     │  │
│  │   (Work)        │                    │   (Home)        │  │
│  │                 │                    │                 │  │
│  │  ┌───────────┐  │                    │  ┌───────────┐  │  │
│  │  │  Claude   │  │                    │  │  Claude   │  │  │
│  │  │  Cursor   │  │                    │  │  Codex    │  │  │
│  │  └─────┬─────┘  │                    │  └─────┬─────┘  │  │
│  │        │        │                    │        │        │  │
│  │        ▼        │                    │        ▼        │  │
│  │  ┌───────────┐  │  push      pull    │  ┌───────────┐  │  │
│  │  │  Source   │──┼────────►───────────┼──│  Source   │  │  │
│  │  │  (git)    │  │   ┌──────────┐     │  │  (git)    │  │  │
│  │  └───────────┘  │   │  GitHub  │     │  └───────────┘  │  │
│  │                 │   │  Remote  │     │                 │  │
│  └─────────────────┘   └──────────┘     └─────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Setup

Option 1: New Setup with Remote

skillshare init --remote git@github.com:you/my-skills.git

This:

  1. Creates source directory
  2. Initializes git
  3. Adds remote
  4. Auto-detects and configures targets

Option 2: Add Remote to Existing

cd ~/.config/skillshare/skills
git init
git remote add origin git@github.com:you/my-skills.git
git add .
git commit -m "Initial commit"
git push -u origin main

Daily Workflow

Machine A: Make Changes and Push

# Edit skills in source or any target
# Then push to remote:
skillshare push -m "Add new pdf skill"

Machine B: Pull and Sync

skillshare pull --remote

That's it. Your skills are now synced across machines.


Commands

Push

Commit and push local changes to remote.

skillshare push                  # Auto-generated commit message
skillshare push -m "Add pdf"     # Custom message

What happens:

┌─────────────────────────────────────────────────────────────────┐
│ skillshare push -m "Add pdf skill"                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ cd ~/.config/skillshare/skills                                  │
│ git add .                                                       │
│ git commit -m "Add pdf skill"                                   │
│ git push origin main                                            │
└─────────────────────────────────────────────────────────────────┘

Pull from Remote

Pull remote changes and sync to all targets.

skillshare pull --remote

What happens:

┌─────────────────────────────────────────────────────────────────┐
│ skillshare pull --remote                                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. cd ~/.config/skillshare/skills                               │
│    git pull origin main                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. skillshare sync (automatic)                                  │
│    Updates all targets with new/changed skills                  │
└─────────────────────────────────────────────────────────────────┘

Second Machine Setup

Setting up a new machine to use your shared skills:

# 1. Clone your skills repo
git clone git@github.com:you/my-skills.git ~/.config/skillshare/skills

# 2. Initialize skillshare (uses existing source)
skillshare init --source ~/.config/skillshare/skills

# 3. Sync to all local targets
skillshare sync

Flow diagram:

┌─────────────────────────────────────────────────────────────────┐
│                   SECOND MACHINE SETUP                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. git clone                                                    │
│                                                                 │
│    GitHub ─────────────────► ~/.config/skillshare/skills/       │
│    Remote                    (your skills are here now)         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. skillshare init --source ~/.config/skillshare/skills         │
│                                                                 │
│    • Detects existing source directory                          │
│    • Auto-detects installed AI CLIs                             │
│    • Creates config.yaml                                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. skillshare sync                                              │
│                                                                 │
│    Source ─────────────────► Claude, Cursor, Codex, ...         │
│    (symlinks created)                                           │
└─────────────────────────────────────────────────────────────────┘

Conflict Handling

Push Fails (Remote Ahead)

$ skillshare push
Error: remote has changes. Run 'skillshare pull --remote' first.

Solution:

skillshare pull --remote   # Get remote changes first
skillshare push            # Now push works

Pull Fails (Local Uncommitted Changes)

$ skillshare pull --remote
Error: local has uncommitted changes. Run 'skillshare push' first.

Solution:

skillshare push -m "Save local changes"
skillshare pull --remote

Merge Conflicts

If git encounters merge conflicts:

cd ~/.config/skillshare/skills
git status                    # See conflicted files
# Edit files to resolve conflicts
git add .
git commit -m "Resolve conflicts"
skillshare sync               # Sync resolved changes

Tips

Private Repository

Use SSH URL for private repos:

skillshare init --remote git@github.com:you/private-skills.git

Check Remote Status

skillshare status
# Shows: Git: clean (remote: origin) or Git: 2 commits ahead

Multiple Remotes

You can add multiple remotes manually:

cd ~/.config/skillshare/skills
git remote add backup git@gitlab.com:you/skills-backup.git
git push backup main