Skip to main content

Cross-Machine Sync

Sync your skills across multiple computers using git.

Overview​

First Machine Setup​

Interactive (guided prompts)​

skillshare init --remote [email protected]:you/my-skills.git

Non-interactive (no prompts)​

# Remote already has your skills (or start fresh source)
skillshare init --remote [email protected]:you/my-skills.git --no-copy --all-targets --no-skill

# First machine with existing Claude skills: import during init
skillshare init --remote [email protected]:you/my-skills.git --copy-from claude --all-targets --no-skill

This:

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

Optional later (only if you install additional AI CLIs after setup):

skillshare init --discover

Then push your skills:

skillshare push
Already initialized?

Add a remote to an existing setup:

skillshare init --remote [email protected]:you/my-skills.git

This works even after initial setup — it just adds the remote.

Second Machine Setup​

On a new machine, the same command works:

skillshare init --remote [email protected]:you/my-skills.git

Init automatically detects that the remote has existing skills and pulls them down. No manual git clone needed.

What happens behind the scenes
  1. Creates source directory and initializes git
  2. Adds remote and runs git fetch
  3. Detects remote has skills → resets local to match remote
  4. Sets up tracking branch
  5. Auto-detects and configures local targets

If you prefer manual control:

# Clone directly, then init with existing source
git clone [email protected]:you/my-skills.git ~/.config/skillshare/skills
skillshare init --source ~/.config/skillshare/skills
skillshare sync

Daily Workflow​

Machine A: Make changes and push​

# Edit skills (changes visible immediately via symlinks)
$EDITOR ~/.config/skillshare/skills/my-skill/SKILL.md

# Optional: create a local checkpoint without pushing
skillshare commit -m "Update my-skill"

# Push to remote when ready to share
skillshare push -m "Update my-skill"

Machine B: Pull and sync​

skillshare pull

That's it. pull automatically runs sync after pulling.

Commands​

Commit​

Create a local checkpoint without pushing:

skillshare commit                  # Default message
skillshare commit -m "Add pdf"     # Custom message
skillshare commit --dry-run        # Preview

What happens:

git add -A
git commit -m "Add pdf"

commit does not require a remote and never pushes.

Push​

Commit and push local changes:

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

What happens:

git add -A
git commit -m "Add pdf"
git push          # auto-sets upstream on first push

Pull​

Pull remote changes and sync:

skillshare pull

What happens:

git pull           # or fetch + reset on first pull
skillshare sync

Conflict Handling​

Pull fails (local uncommitted changes)​

If you want to keep the local changes but are not ready to push them yet, commit them locally first:

skillshare commit -m "Save local changes"
skillshare pull

Push fails (remote ahead)​

$ skillshare push
Push failed
  Remote may have newer changes
  Run: skillshare pull
  Then: skillshare push

Solution:

skillshare pull
skillshare push

Pull still fails with local uncommitted changes​

$ skillshare pull
Local changes detected
  Run: skillshare push
  Or:  cd ~/.config/skillshare/skills && git stash

Solution:

# Option 1: Commit locally first
skillshare commit -m "Local changes"
skillshare pull

# Option 2: Push your changes first
skillshare push -m "Local changes"
skillshare pull

# Option 3: Stash changes temporarily
cd ~/.config/skillshare/skills
git stash
skillshare pull
git stash pop

Merge conflicts​

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

Check Status​

skillshare status

Shows:

  • Git status (clean, ahead, behind)
  • Remote configuration
  • Sync status

Private Repository​

Use SSH URL for private repos:

skillshare init --remote [email protected]:you/private-skills.git

Tips​

Use SSH keys​

Set up SSH keys to avoid password prompts:

ssh-keygen -t ed25519 -C "[email protected]"
# Add public key to GitHub

Portable paths for dotfiles​

If you share config.yaml via dotfiles, enable preserve_tilde_on_save to keep paths as ~/... instead of /home/alice/...:

preserve_tilde_on_save: true

This prevents noisy diffs when the same config is used across machines with different usernames or OS-specific home prefixes. See Configuration — preserve_tilde_on_save.

Multiple remotes​

Add backup remotes:

cd ~/.config/skillshare/skills
git remote add backup [email protected]:you/skills-backup.git
git push backup main

Sync on shell startup​

Add to ~/.bashrc or ~/.zshrc:

# Sync skillshare on terminal open (if remote configured)
skillshare pull 2>/dev/null

Alternative: Install from Config​

If you don't want to set up a git remote, config.yaml doubles as a portable skill manifest. Every install / uninstall auto-updates the skills: section, and skillshare install (no args) reinstalls everything listed:

# Machine A — config.yaml records what you installed
skillshare install anthropics/skills -s pdf
# config.yaml now has: skills: [{name: pdf, source: "..."}]

# Machine B — copy config.yaml, then:
skillshare install      # Installs all listed skills
skillshare sync

When to use which​

push / pullinstall (no args)
What's syncedActual skill files (full content)Source URLs only — re-downloads on install
Local/hand-written skillsIncludedNot included (no source URL)
Setup requiredGit remote on source dirJust config.yaml
Project modeGlobal onlyWorks with -p (.skillshare/config.yaml)
MaintenanceManual push after changesAuto-reconciled on install/uninstall

Recommendation: Use push/pull for personal cross-machine sync. Use install from config for team onboarding and project setup.

See Also​