Context

NanoClaw users fork the repo and customize it — changing config values, editing source files, modifying personas, adding skills. When upstream ships updates or refactors, git merge produces painful conflicts because the same core files were changed on both sides.

This skill extracts the user's customizations into a migration guide — capturing both the intent (what they want) and the implementation details (how they did it, with code snippets, API calls, and specific configurations). On upgrade, it checks out clean upstream in a worktree, then reapplies customizations using the guide. No merge conflicts because there's nothing to merge.

The migration guide is markdown, not structured data. It needs to capture the full range of what a user might customize, with enough implementation detail that a fresh Claude session can reapply it without having seen the original code. Standard changes (config values, simple logic) can be described briefly. Non-standard changes (specific APIs, custom integrations, unusual patterns) need code snippets and precise instructions.

Two phases: Extract (build the migration guide) and Upgrade (use it). If a guide already exists, offer to skip to Upgrade.

Principles

• Never proceed with a dirty working tree.
• Always create a rollback point (backup branch + tag) before touching anything.
• The migration guide is the source of truth, not diffs.
• Use a worktree to validate before affecting the live install.
• Data directories (groups/, store/, data/, .env) are never touched — only code.
• Be helpful: offer to do things (stash, commit, stop services) rather than telling the user to do them.
• Use sub-agents for exploration. Spawn haiku sub-agents to explore the codebase, trace skill merges, diff files, and identify customizations. This keeps the main context focused on the user conversation and decision-making.