Sync Dotfiles

sync-dotfiles

Propagate intentional edits to your local agent/editor config back into a dotfiles git repo so they ship to your other machines.

This skill is config-agnostic: it asks you where your dotfiles repo lives and which sources to sync. It never hardcodes a private path.

Core safety model

• Only copy when BOTH source and destination already exist. This prevents

introducing new tracked files implicitly — adding a new tracked file is a deliberate, manual cp, not a side effect of sync.

• Never git push and never git commit --amend — local commit only.
• Never write outside the dotfiles repo.
• Skip per-machine churn files (e.g. ~/.claude/settings.local.json).

Step 1 — Locate the dotfiles repo

Ask the user for their dotfiles repo path if you don't already know it.

Where is your dotfiles repo? (absolute path, e.g. ~/dotfiles or
~/Repositories//dotfiles)

Set DOTFILES="". If [ ! -d "$DOTFILES/.git" ], report that it's not a git repo and stop.

> Tip: if the user syncs often, suggest they record the path in their project > or global CLAUDE.md so this skill can skip the question next time.

Step 2 — Agree on the sync list

Ask which sources to sync (offer the common defaults; let them add/remove). Each entry is a source → destination pair where the destination is a path inside $DOTFILES. Common defaults:

| Source (local) | Destination (in repo) | Copy mode | |---|---|---| | ~/.claude/CLAUDE.md | /.claude/CLAUDE.md | file | | ~/.claude/settings.json | /.claude/settings.json | file | | ~/.claude/skills/ | /.claude/skills/ | rsync -aL --delete | | ~/.cursor/cli-config.json | /.cursor/cli-config.json | file | | ~/.cursor/mcp.json | /.cursor/mcp.json | file | | ~/.cursor/rules/ | /.cursor/rules/ | rsync -a --delete |

Confirm the destination layout matches how the user's repo is actually organised (some keep config at the repo root, others under a dotfiles/ or .config/ subdir). Adjust the destination paths to match before copying.

Exclusions to confirm with the user:

• ~/.claude/settings.local.json — per-machine accept-list churn, skip.
• Any local-only skill that symlinks to a sibling repo not present on every

machine — exclude from the rsync (e.g. --exclude='browser-harness/').

Step 3 — Verify a clean baseline for the tracked paths

git -C "$DOTFILES" status --porcelain 

If non-empty, show the user and ask: continue, stash, or abort. Default abort.

Step 4 — Copy (only when both source and destination exist)

For each file pair:

if [ -f "$SRC" ] && [ -f "$DST" ]; then
    cp -f "$SRC" "$DST"
fi

For each directory pair (use -L to dereference symlinks so symlinked skills/configs are captured as real files and the repo stays portable):

if [ -d "$SRC" ] && [ -d "$DST" ]; then
    rsync -aL --delete --exclude='' "$SRC" "$DST"
fi

Never copy excluded files (e.g. settings.local.json).

Step 5 — Show the diff

git -C "$DOTFILES" diff --stat 
git -C "$DOTFILES" diff 

If the diff is empty, report "no changes to sync" and stop.

Step 6 — Draft a commit message and confirm

Draft a Conventional Commits message from what changed. Examples:

• chore(claude): update settings.json — add pnpm permission
• chore(cursor): sync mcp.json from machine
• chore(claude,cursor): propagate hook updates

Show the user the proposed message. Ask: approve, edit, or abort.

Step 7 — Commit (on approval only)

git -C "$DOTFILES" add 
git -C "$DOTFILES" commit -m ""
git -C "$DOTFILES" rev-parse --short HEAD

Report the commit SHA. Do NOT git push. Do NOT --amend.

Hard rules

• Never touch per-machine churn files (settings.local.json and similar).
• Never git push. Never --amend.
• Never write to any path outside $DOTFILES.
• Only copy when both source and destination already exist. Adding a new

tracked file requires an explicit, deliberate cp — this skill will not introduce new tracked files on its own.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mauriciovieira
• Source: mauriciovieira/skills
• License: MIT

Install and usage instructions live in the source repository linked above.