cursor-sync

Personal Cursor configuration in Git: rules, slash commands, and agent skills. Clone once, point your Cursor config directories at this repo (or copy the folders), then pull to stay up to date across machines.

What’s in the repo

Folder	Cursor location	Purpose
cursor-rules/	User rules (~/.cursor/rules/)	Always-on or requestable guidance (.mdc files)
cursor-skills/	User skills (~/.cursor/skills/)	Agent skills (TDD, Playwright, git helpers, framework experts, etc.)
cursor-commands/	Slash commands (~/.cursor/commands/)	Short prompts (e.g. changelog helpers). Prefer skills for git workflows.
agents/skills/	Agent skills (~/.agents/skills/)	Cross-agent skills (diagnose, handoff, grill-me, …)
scripts/	(not installed into Cursor)	csync, pull-on-start, and hierarchy-aware skills CLI wrappers

Git workflows live as user skills under cursor-skills/ (linked to ~/.cursor/skills/). Invoke them by name in chat — start with the git router skill for the menu. Slash commands that still exist are thin prompts, not git entry points.

This repo does not include Cursor’s built-in ~/.cursor/skills-cursor/ skills.

Quick start

1. Clone

git clone https://github.com/MarcoAntolini/cursor-sync.git
cd cursor-sync

Pick any directory you like (e.g. ~/cursor-sync or C:\Users\you\cursor-sync).

2. Link into Cursor (recommended)

Linking keeps one source of truth: edits and git pull apply everywhere Cursor reads config.

macOS / Linux — create parent dirs if needed, then symlink:

mkdir -p ~/.cursor ~/.agents

ln -sfn "$(pwd)/cursor-rules"   ~/.cursor/rules
ln -sfn "$(pwd)/cursor-skills"  ~/.cursor/skills
ln -sfn "$(pwd)/cursor-commands" ~/.cursor/commands
ln -sfn "$(pwd)/agents/skills"  ~/.agents/skills

Windows (PowerShell, run as your user) — use directory junctions or symlinks. Enable Developer Mode if mklink requires it.

$Repo = "C:\Users\you\cursor-sync"   # your clone path

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor" | Out-Null
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents" | Out-Null

cmd /c mklink /D "$env:USERPROFILE\.cursor\rules"    "$Repo\cursor-rules"
cmd /c mklink /D "$env:USERPROFILE\.cursor\skills"   "$Repo\cursor-skills"
cmd /c mklink /D "$env:USERPROFILE\.cursor\commands" "$Repo\cursor-commands"
cmd /c mklink /D "$env:USERPROFILE\.agents\skills"   "$Repo\agents\skills"

If a real folder already exists at the target (e.g. ~/.cursor/rules), rename or back it up before linking.

3. Verify

1. Restart Cursor (or reload the window).
2. Settings → Rules: you should see rules from cursor-rules/.
3. In chat, invoke a skill by name (e.g. git, git-commit, TDD, diagnose).
4. Optionally type / for remaining slash commands (e.g. changelog helpers).

Alternative: copy instead of link

If you do not want symlinks:

cp -R cursor-rules   ~/.cursor/rules
cp -R cursor-skills  ~/.cursor/skills
cp -R cursor-commands ~/.cursor/commands
cp -R agents/skills  ~/.agents/skills

You must re-copy (or merge manually) when you pull updates from upstream.

Daily workflow: csync (optional)

After you change rules, skills, or commands (in Cursor or in this repo), sync to GitHub with one command instead of cd, add, commit, pull, and push by hand.

scripts/csync.ps1 and scripts/csync.sh stage everything, commit only if there are changes, then pull --rebase --autostash and push (quiet). Default commit message is a timestamp; pass a custom message as the first argument.

Scripts resolve the repo from their own location. If your clone lives elsewhere, set CURSOR_SYNC to its path (e.g. C:\Users\you\dev\cursor-sync or /opt/dotfiles/cursor-sync).

Install csync

Add one line to your shell profile ($PROFILE on Windows, ~/.bashrc or ~/.zshrc on macOS/Linux). Adjust the path to match where you cloned:

Windows (PowerShell):

. "$env:USERPROFILE\cursor-sync\scripts\csync.ps1"

macOS / Linux (bash/zsh):

source ~/cursor-sync/scripts/csync.sh

Reload the shell, then:

csync                            # message: sync <timestamp>
csync "add TDD skill tweaks"     # custom message

You can also run a one-off sync without loading your profile:

pwsh -File "$env:USERPROFILE\cursor-sync\scripts\csync.ps1" "optional message"

~/cursor-sync/scripts/csync.sh "optional message"

With symlinks, Cursor writes directly into this repo, so csync is usually all you need on the machine where you edited.

Pull on shell start (optional)

On a second machine, you often only need the latest config from GitHub. scripts/pull-on-start.ps1 and scripts/pull-on-start.sh run a silent background git pull --rebase when you open a shell (no commit or push).

Windows (PowerShell) — add to $PROFILE (in addition to csync if you use it):

. "$env:USERPROFILE\cursor-sync\scripts\pull-on-start.ps1"

macOS / Linux:

source ~/cursor-sync/scripts/pull-on-start.sh

Respects CURSOR_SYNC the same way as csync. Skip this if you prefer to pull manually or only use csync on that machine.

Nested skills CLI: skills (optional)

Global agent skills often live in nested folders under ~/.agents/skills/ (for example mattpocock/…). The official npx skills update flattens them. scripts/skills-cli/ is a hierarchy-aware wrapper (skills-tree) that updates skills in place and keeps nested paths.

Windows (PowerShell) — add to $PROFILE:

. "$env:USERPROFILE\cursor-sync\scripts\skills.ps1"

macOS / Linux:

source ~/cursor-sync/scripts/skills.sh

Reload the shell, then:

skills check                 # should print a skills-tree header first
skills update                # update, preserving nested locations
skills locations             # list root vs nested installs
Get-Command skills           # PowerShell: confirm it points at skills-tree

If skills check hangs with only a GitHub rate-limit message and no skills-tree header, you are hitting the official CLI directly (wrapper not loaded) or unauthenticated API limits — run gh auth login / set GITHUB_TOKEN, then re-source the wrapper above.

Other commands are forwarded to npx skills. See scripts/skills-cli/README.md.

Manual sync

If you prefer not to install csync:

cd ~/cursor-sync   # or your clone path
git add -A && git commit -m "sync" && git pull --rebase --autostash && git push

With copies instead of symlinks, you still need to re-copy or merge after pulling on another machine.

Making it yours

1. Fork the repository on GitHub (or clone and use your own remote).
2. Edit rules, skills, and commands in this repo; Cursor reads them via the links above.
3. Commit and push from cursor-sync like any other dotfiles repo.

To override something for a single project only, use that project’s .cursor/rules/ or .cursor/skills/ — project rules can stack with user rules.

Per-machine notes

• Paths differ by OS (~/.cursor vs %USERPROFILE%\.cursor), but the four mappings are the same.
• Do not commit secrets (API keys, .env, tokens). This repo is intended for prompts and tooling only.
• Line endings are normalized to LF (see .gitattributes).