Migrate NanoClaw
Extract your customizations into a replayable migration guide, then upgrade to upstream by reapplying them on a clean base instead of merging.
What it does
- Extracts your customizations into a markdown migration guide
- Upgrades by reapplying customizations on a clean upstream checkout — no merge conflicts
- Creates a backup branch and tag before touching anything
- Validates the upgrade in a git worktree before swapping it into your install
- Reapplies installed skills by re-running each skill's own apply
- Optional live test against real data before the swap
What you'll need
- NanoClaw installed as a git clone or fork (not a downloaded zip)
- An upstream remote configured, or the URL to add it
- A clean working tree — the skill offers to stash or commit if not
Install
/migrate-nanoclaw How it works
The /migrate-nanoclaw skill replaces merge-based upgrades with an intent-based migration. Instead of running git merge and fighting conflicts on core files both you and upstream changed, it captures what you customized and how, then reproduces those changes on a fresh upstream checkout where there is nothing to merge.
It works in two phases: Extract, which builds the migration guide, and Upgrade, which uses it. If a guide already exists, the skill offers to skip straight to the upgrade.
Before anything else, the skill refreshes itself from upstream so you always run the newest version of the migration process. It also assesses the scale of your divergence and picks the lightest path that fits — a small fork might be pointed at /update-nanoclaw instead, while a heavily customized one gets the full treatment with parallel sub-agents.
Extract
The skill checks that your working tree is clean (offering to stash or commit if not), confirms the upstream remote, and fetches the latest commits. It then spawns Haiku sub-agents to explore the fork: which files changed, which commits you made, and which add-* skills you installed along with the files each one owns.
From there it separates skill-owned files (reapplied later by re-running each skill) from your own customizations, and analyzes the rest. For standard changes — config values, simple logic — it records the intent briefly. For non-standard changes — specific APIs, custom integrations, unusual patterns — it captures code snippets, import paths, and configuration verbatim, so a fresh Claude session can reproduce them without ever seeing the original diff.
The result is written to .nanoclaw-migrations/guide.md (or a directory of section files for complex forks), verified against the actual code, and offered up as a commit.
Upgrade
The skill re-runs its preflight checks, then creates a rollback point:
git branch backup/pre-migrate-<hash>-<timestamp>
git tag pre-migrate-<hash>-<timestamp>It previews upstream’s changes — including any [BREAKING] changelog entries — then checks out clean upstream in a .upgrade-worktree. Inside the worktree it reapplies each installed skill by running that skill’s own apply, then works through the customizations in the guide one by one. It validates with pnpm install && pnpm run build && pnpm test, and optionally lets you run a live test against your real data before committing.
Once you’re satisfied, it swaps the upgraded worktree into your main tree with git reset --hard, restores the migration guide, stamps the upgrade marker, and restarts the service. Your data directories — groups/, store/, data/, and .env — are never touched. Only code moves.
Tips
- The migration guide is the source of truth, not diffs — keep it committed so future upgrades build on it.
- Rollback is always one command:
git reset --hard pre-migrate-<hash>-<timestamp>. The exact tag is printed at the end of every run. - If your fork barely diverges from upstream, the skill will suggest
/update-nanoclawas the simpler path — take it. - After an upgrade, the startup tripwire expects the upgrade marker to be stamped; the skill does this for you once the build passes.