diff --git a/.claude/skills/sync-upstream/SKILL.md b/.claude/skills/sync-upstream/SKILL.md
new file mode 100644
index 0000000..311402c
--- /dev/null
+++ b/.claude/skills/sync-upstream/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: sync-upstream
+description: Rebase this fork onto the latest IceRhymers/databricks-claw upstream
+user-invocable: true
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+# Sync Fork with Upstream
+
+Rebase the current fork onto the latest upstream IceRhymers/databricks-claw. This skill walks through the full sync: fetch, preview, rebase, conflict guidance, and test.
+
+## Workflow
+
+### Step 1 — Ensure upstream remote
+
+Run `git remote -v` in the repo root.
+
+If no remote named `upstream` exists, add it:
+
+```bash
+git remote add upstream https://github.com/IceRhymers/databricks-claw.git
+```
+
+If `upstream` already exists, confirm it points to `IceRhymers/databricks-claw`. If it points elsewhere, warn the user and ask before changing it.
+
+### Step 2 — Fetch latest upstream
+
+```bash
+git fetch upstream
+```
+
+### Step 3 — Show what's new
+
+Run:
+
+```bash
+git log HEAD..upstream/main --oneline
+```
+
+Print the output so the user can review incoming commits. If there are no new commits, tell the user the fork is already up to date and stop here.
+
+### Step 4 — Create a sync branch
+
+Create a dated branch from the current HEAD:
+
+```bash
+git checkout -b sync/upstream-$(date +%Y%m%d)
+```
+
+This keeps the user's current branch untouched in case something goes wrong.
+
+### Step 5 — Rebase onto upstream
+
+```bash
+git rebase upstream/main
+```
+
+If the rebase succeeds cleanly, move on to Step 7.
+
+### Step 6 — Guide conflict resolution
+
+If the rebase hits conflicts, help the user resolve them. Common conflict hotspots in databricks-claw forks:
+
+- `claw/core/mcp_mapper.py` — custom MCPs added to the fork. Keep both upstream bug fixes and the fork's custom MCP registrations.
+- `claw/core/config.py` — custom env vars or feature flag defaults. Preserve the fork's custom defaults while accepting any new upstream config keys.
+- `CLAUDE.md` — custom instructions for Claude. Keep the fork's personality/instruction customizations; merge in any new upstream sections.
+- `alembic/versions/` — if the fork has custom migrations, check ordering. Upstream may have added new migrations that need to come before or after the fork's. Verify the `down_revision` chain is unbroken.
+
+General principle: keep BOTH sides when appropriate. Upstream brings bug fixes, new features, and structural improvements. The fork brings customizations. Merge them together rather than picking one side.
+
+After resolving each file, run:
+
+```bash
+git add <resolved-file>
+git rebase --continue
+```
+
+Repeat until the rebase completes.
+
+### Step 7 — Run tests
+
+```bash
+python -m pytest tests/ -x -q
+```
+
+Report the result count (passed, failed, skipped). If tests fail, investigate and help the user fix before proceeding.
+
+### Step 8 — Summarize
+
+Print a summary:
+
+- Number of upstream commits rebased
+- Files changed (`git diff --stat HEAD~N..HEAD` where N is the number of rebased commits)
+- Any conflicts that were resolved and how
+- Test results (pass/fail count)
+- Next step: remind the user to force-push the sync branch and open a PR to merge it into their fork's main branch