Guide · Agent skill
How to use the NanoClaw Migration Assistant agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The migrate-nanoclaw skill is an agent skill for the NanoClaw project that helps an AI agent upgrade a forked copy of NanoClaw. Instead of running git merge against upstream and resolving conflicts, the agent records your customizations in a markdown migration guide and reapplies them on a clean upstream base. This guide explains what the skill does, how to install it, how to trigger it and what to check before letting it touch your code.
NanoClaw Migration Assistantnanocoai/nanoclaw · MIT Download the skill Quick start
- 1Download and unzip. Download the migrate-nanoclaw ZIP from this page and unzip it. Keep the folder name migrate-nanoclaw.
- 2Place the skill folder. Move the folder into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ for one project. Alternatively upload the ZIP under Settings → Capabilities → Skills.
- 3Confirm your fork is ready. Make sure your NanoClaw fork is checked out locally with git available and a clean or committable working tree.
- 4Ask in plain language. Describe the upgrade you want, for example asking to upgrade your fork to the latest upstream without merge conflicts.
- 5Answer the scope and stash questions. Respond to the tier assessment and the working tree prompt so the agent knows whether to use the lightweight or full path.
- 6Extract and review the guide. Let the agent build the migration guide, then read it and confirm each recorded customization still reflects your intent.
- 7Upgrade in a worktree and review. Let the agent reapply changes on clean upstream in a worktree, test the result and only then move it into your live install.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file and optional supporting files that an AI agent loads when a request matches the skill's description. The skill gives the agent a defined procedure to follow.
The migrate-nanoclaw skill works in two phases. In Extract, the agent catalogs your customizations (config changes, edited source files, persona edits and added skills) into a markdown migration guide that includes enough implementation detail for a fresh session to reapply them. In Upgrade, when upstream releases changes, the agent checks out clean upstream code in a separate worktree and reapplies your changes from that guide.
- Creates a rollback point (backup branch and tag) before changing anything
- Validates the upgrade in a worktree before affecting your live install
- Leaves data directories groups/, store/, data/ and .env untouched; only code is changed
Install the migrate-nanoclaw skill
Download the skill ZIP from this page and unzip it. For a personal install that applies to all your projects, place the migrate-nanoclaw folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/migrate-nanoclaw/
- Project only: <your-project>/.claude/skills/migrate-nanoclaw/
Check your NanoClaw fork before you start
The skill assumes a git-based fork of NanoClaw with a local working tree. It needs git, network access to the upstream repository at https://github.com/nanocoai/nanoclaw.git, and Bash tool access so the agent can run git commands. Your working tree should be clean or committable; the skill will not proceed with a dirty tree.
- git installed and the fork checked out locally
- Network access to fetch from upstream
- Bash tool access for the agent
- Clean or committable working tree
How do you trigger the skill with natural requests?
You do not need a special command. Describe what you want in plain language and the agent will match the request to the skill. Requests like the ones below are the kind the skill is written for.
If a migration guide already exists, the skill offers to skip straight to the Upgrade phase. If your fork has only a few changes, the skill suggests the lighter /update-nanoclaw approach and lets you choose.
- "Upgrade my NanoClaw fork to the latest upstream without merge conflicts."
- "Extract my NanoClaw customizations into a migration guide."
- "Reapply my customizations on top of the new upstream release."
What to expect during a run
The agent first refreshes the skill itself from upstream, then runs preflight checks. It asks you how to handle uncommitted changes (stash, commit or handle it yourself) and measures how far your fork has diverged from upstream. Based on the scope it picks a tier: lightweight, standard or complex. Exploration is delegated to sub-agents so your conversation stays focused on decisions.
The agent asks targeted questions only where intent is unclear from the code. It is designed to offer to perform steps such as stashing, committing or stopping services rather than asking you to run them.
- Preflight: clean tree check and upstream remote setup
- Scope assessment and tier selection
- Guide creation or update, then Upgrade in a worktree
Safety notes: scripts and network access
This skill runs scripts and uses the network. Its procedure includes git fetch from the upstream repository and git commands that create branches, tags, stashes or commits. Depending on the upgrade, it may also stop services. Review the SKILL.md before first use.
The skill also includes a diagnostics step. The diagnostics document describes writing a JSON summary to /tmp/nanoclaw-diagnostics.json and sending it to an analytics endpoint, but only after you are shown the full JSON and choose Yes. It says it includes no paths, usernames, hostnames or IP addresses. You can answer No, and you can review the file before any submission.
Do not run it unattended on a live production install. Use a test copy or review each step.
- Runs git fetch and creates branches, tags, stashes or commits
- May stop services during upgrade
- Diagnostics submission is opt-in after you review the JSON
What people use it for
- Upgrading a heavily customized NanoClaw fork whose config, source and persona edits conflict with each upstream release
- Recording why each local change was made so a teammate or a fresh agent session can reapply it
- Checking whether a small fork should use /update-nanoclaw instead of the full migration process
- Updating an existing migration guide with only the commits added since it was generated
Frequently asked questions
How do I install the migrate-nanoclaw skill?
Download the skill ZIP from this page and unzip it. Place the migrate-nanoclaw folder in ~/.claude/skills/ for all projects, or in your project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to use the migrate-nanoclaw skill?
You need git, a locally checked-out NanoClaw fork with a clean or committable working tree, network access to https://github.com/nanocoai/nanoclaw.git, and Bash tool access so the agent can run git commands.
Is the migrate-nanoclaw skill free and what is its licence?
The skill is listed under the MIT licence. This page does not state any price, so check the source repository for licence terms and details.
Is there a simpler alternative for small NanoClaw forks?
Yes. The skill itself suggests the lighter /update-nanoclaw approach for forks with only a few changes, since the full migration process adds overhead. The skill will offer this option when the scope is small.
Why does the skill refuse to run with uncommitted changes?
Its principles say never to proceed with a dirty working tree. The agent will offer to stash or commit your changes first, using git stash push or a commit with a descriptive message.
Will this skill delete my data or .env file?
The skill is designed to leave groups/, store/, data/ and .env untouched and to change only code. It also creates a backup branch and tag before touching anything so you have a rollback point.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain a heavily customized NanoClaw fork and find git merge upgrades painful, or if your team wants a written record of why each local change exists. Pick /update-nanoclaw or a plain git merge for small forks, and avoid unattended runs on a live production install.
Download the skill