migrate-nanoclaw
Extracts user customizations from a fork, generates a replayable migration guide, and upgrades to upstream by reapplying customizations on a clean base. Replaces merge-based upgrades with intent-based migration.
Profile →npx skills add nanocoai/nanoclaw --skill migrate-nanoclaw --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Extracts user customizations from a fork, generates a replayable migration guide, and upgrades to upstream by reapplying customizations on a clean base. Replaces merge-based upgrades with intent-based migration.
How it works
- The skill describes a two-phase process: Extract and Upgrade. In Extract, it builds a migration guide that captures both the intent and implementation details of user customizations, including code snippets and configurations for non-standard changes. In Upgrade, it checks out a clean upstream worktree and reapplies customizations using the migration guide, avoiding merge conflicts.
- It uses a worktree workflow, creates a rollback point (backup branch and tag) before touching anything, and treats the migration guide as the source of truth rather than diffs.
- It avoids touching data directories and focuses only on code changes. It employs sub-agents to explore the codebase, identify customizations, and summarize changes per skill or file.
- It defines two phases: Extract and Upgrade, with multiple sub-steps for preflight, scope assessment, guide writing, and potential plan formation for complex migrations.
When to use it
- Use when upgrading Nanoclaw forks where upstream updates are substantial and a merge-based upgrade would cause conflicts due to overlapping changes in core files.
- Use when user customizations are spread across config values, source files, and integrations, and there is a desire to reapply them deterministically on upstream.
- Use when a migration guide already exists to decide between updating it or re-extracting; the workflow supports both paths.
What it can touch
- Code directories only; data directories (groups/, store/, data/, .env) are never touched. The process emphasizes upgrading by reapplying customizations on a clean upstream base via a migration guide.
- It prescribes absolute-path usage for worktrees and relies on git commands and sub-agents to inspect and summarize changes.
Caveats
- The workflow requires maintaining a migration guide as the single source of truth and relies on a clean upstream worktree to reapply changes.
- It may involve creating and managing worktrees, backup branches, and tags before applying migrations.
- The license for the skill is MIT, and it uses claude-code as a declared tool.
# 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
- 1.0 Preflight
- 1.1 Assess scope and determine path
- Tier 1: Lightweight — suggest /update-nanoclaw instead
- Tier 2: Standard
- Tier 3: Complex
- 1.2 Update existing guide (if applicable)
- 1.3 Explore the codebase
- 1.4 Analyze customizations
- 1.5 Confirm with user
- 1.6 Migration plan (Tier 3 only)
- 1.7 Write the migration guide
- 2.0 Preflight
- 2.1 Safety net
- 2.2 Preview upstream changes
Divergence stats git rev-list --count $BASE..upstream/$UPSTREAM_BRANCH # upstream commits git rev-list --count $BASE..HEAD # user commits git diff --name-only $BASE..HEAD | wc -l # user changed files git diff --stat $BASE..HEAD | tail -1 # insertions/deletions git diff --name-only $BASE..upstream/$UPSTREAM_BRANCH | wc -l # upstream changed files git add .nanoclaw-migrations/ git commit -m "chore: save migration guide" git branch backup/pre-migrate-$HASH-$TIMESTAMP git tag pre-migrate-$HASH-$TIMESTAMP
What does the migrate-nanoclaw skill do?
Extracts user customizations from a fork, generates a replayable migration guide, and upgrades to upstream by reapplying customizations on a clean base. Replaces merge-based upgrades with intent-based migration.
How do I install it?
Run `npx skills add nanocoai/nanoclaw --skill migrate-nanoclaw --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From nanocoai/nanoclaw, a repository with 30,426 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.