How to Sync Claude Code Skills Across Machines

You write a skill on the work laptop. Two days later you're on the home desktop and Claude Code has no idea that skill exists. Skills live as folders under ~/.claude/skills/ (and project copies under .claude/skills/), and Claude Code does not sync them for you. Anthropic's own issue tracker has an open thread asking for built-in sync — until that exists, you need a deliberate way to move skills between machines.

This is a practical guide to how to sync Claude Code skills across machines: what to copy, what to leave alone, the git + symlink pattern most people start with, where that pattern breaks, and when a background agent is the cleaner option.

What syncs, and what must stay local

A skill is a directory with a SKILL.md inside it. Personal skills live in ~/.claude/skills/<name>/. Project skills live in the repository. Those two scopes matter:

If you copy the whole ~/.claude tree with Dropbox or iCloud, you will eventually fight merge conflicts on session files and risk shipping tokens. Sync the portable layer only.

Option 1: private git repo + symlinks

This is the pattern Reddit and HN threads converge on: keep portable config in a private repository, then link or copy it into place on each machine.

1. Create a private GitHub repo (for example yourname/claude-skills).
2. On the machine that already has skills, copy ~/.claude/skills/ into that repo and push.
3. On each other machine, clone the repo somewhere stable (~/src/claude-skills), then either:
   • symlink ~/.claude/skills → the repo's skills/ folder, or
   • run a small install script that copies or links each skill folder.
4. After you edit a skill, commit and push. On the other machine, pull before you expect the skill to appear.

Gotchas that show up in real setups:

• Windows symlink friction. Git may check symlinks out as plain text unless core.symlinks and Developer Mode (or admin) are enabled. Prefer a copy/install script on Windows instead of fighting junctions.
• Stale skill cache. Some users report Claude Code continuing to use an older skill body after a pull until the session reloads the skill from disk. If a skill looks outdated after sync, start a fresh session or re-invoke the skill explicitly.
• Machine-specific paths. Don't put absolute paths to one machine's home directory inside SKILL.md scripts. Prefer relative paths or $HOME.

A bare git repo is free and transparent. You own the files. You also own the push/pull discipline — skip a pull and the "synced" machine lies to you.

Option 2: skill-only sync tools

A cluster of small tools appeared because the gap is obvious: agent-skills-sync (VS Code extension that polls a private GitHub repo for Claude Code / Codex / Cursor skill folders), sync-my-skills (slash-command push/pull into a private repo with symlinks), and gist- or git-backed CLIs such as claudesync that cover skills plus settings and hooks.

These are better than ad-hoc scp when you only care about skills and want automatic upload after edits. They still leave MCP server registration, multi-harness config formats, and marketplace installs as separate problems — and you still maintain a git remote as the source of truth.

Option 3: treat skills as product installs, not just files

File sync answers "how do I copy folders." It does not answer "how do I install the same skill set on every laptop without remembering which machine is ahead."

That is the job loadout is built for. Pair each machine, install a skill once from the dashboard (or from the marketplace), and a background agent on each paired machine writes the skill into place. No pull step before you sit down to work. Project skills still belong in the repo; personal skills and marketplace installs are what loadout keeps aligned.

See how syncing works and how to add skills to Claude Code if you are still writing your first SKILL.md.

If your "sync" requires you to remember to pull before opening Claude Code, it will fail on the morning you are in a hurry.

A checklist for a new machine

1. Install Claude Code and sign in.
2. Confirm ~/.claude/skills/ exists (Claude creates it when needed).
3. Apply your sync method: clone + link, run the skill sync tool, or pair the machine in loadout.
4. Run /skills and confirm the names you expect.
5. Trigger one skill you know well — if the description matches but the behavior is old, reload the session.

FAQ

Does Claude Code sync skills across machines by itself?

No. Skills are files on disk. Claude.ai-linked skills can sync into ~/.claude/skills/synced/ on a signed-in machine, but there is no built-in multi-machine fleet sync for everything under ~/.claude/skills/.

Should I sync project skills with a personal sync tool?

Usually no. Put project skills in .claude/skills/ inside the repository so teammates get them on clone. Use personal sync for ~/.claude/skills/ only.

Is Dropbox or iCloud safe for ~/.claude?

Not as a whole-directory sync. Session history and caches churn constantly, and credentials must stay off shared folders. Sync an allowlisted subset, or use a tool that already knows the allowlist.

What is the fastest path if I only have two Macs?

A private git repo of skills/ plus symlinks works. If you also juggle MCP servers and more than one coding harness, a dedicated sync agent saves the glue scripts you would otherwise rewrite every few months.