How to use the Finish v1 to v2 Migration agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI coding agent can load and follow for a specific task. This skill is named migrate-from-v1 and ships as a single SKILL.md file.

The script migrate-v2.sh has already copied most data and settings before this skill runs. The skill then has the agent check the migration log, confirm which user is the bot's owner, set who may message the bot, migrate legacy memory, reconcile configuration, and help port custom code changes. If the script has not run yet, the skill tells you to run it in your own terminal first.

• Reads logs/setup-migration/handoff.json to see the status of each migration step.
• Confirms the owner and grants the owner role in the v2 database.
• Sets the unknown sender policy: public, known users only, or approval required.
• Runs the shared-memory migration (/migrate-memory) for imported groups.
• Reconciles container configuration and helps port custom v1 code.

Install the migrate-from-v1 skill

Download the ZIP from the directory page and unzip it. Then place the resulting migrate-from-v1 folder in one of these locations, depending on whether you want it for all projects or one project.

Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the ZIP there.

• Personal, all projects: ~/.claude/skills/migrate-from-v1/
• Single project: .claude/skills/migrate-from-v1/ inside your NanoClaw project folder
• Claude apps: Settings → Capabilities → Skills → upload the ZIP

Before you start: requirements

The skill assumes a specific setup. It will not work on a generic project. You need NanoClaw v1 and v2 installation files, a completed run of migrate-v2.sh, and access to the v1 SQLite database at store/messages.db and the v2 central database.

The script itself is run in a regular terminal, not inside Claude. It needs Node with pnpm, Docker and OneCLI, because it performs bootstrap, OneCLI setup and a container build.

• NanoClaw v1 and v2 installation files
• A completed run of migrate-v2.sh, run in a regular terminal
• Node and pnpm, Docker, and OneCLI
• Access to store/messages.db (v1) and the v2 central database
• Back up your v1 install first. The skill changes routing and access settings in a live database.

How to trigger the skill with natural requests

The skill is triggered by phrases that match its description. Use one of the trigger phrases in your request to the agent after migrate-v2.sh has finished. The skill first checks that logs/setup-migration/handoff.json exists. If it does not, the agent stops and asks you to run the script first.

• "Migrate from v1"
• "Finish migration"
• "v1 migration"
• Example: "I just ran migrate-v2.sh, finish the v1 migration with me."

Walk through the migration with the agent

The agent first confirms the switch is safe to test. It asks you to stop v1's service and start v2's, tail the host log for a clean boot, and send a real test message. Phase 0 confirms v2 routes real messages before deeper work begins. v1 is paused rather than modified, so reverting is one command.

Next the agent seeds the owner. It lists the users in the database and asks you to confirm which one is you. It then grants the owner role if it is not already present. Finally it discusses the access policy and runs the shared-memory migration for the groups.

• Phase 0: confirm v2 answers a real test message.
• Phase 1: confirm the owner and set access policy.
• Phase 2: run /migrate-memory for imported groups.
• Phase 3: container configuration.

Safety notes: scripts and network

This skill runs scripts. It executes TypeScript that opens the v2 central database and grants roles, and it can run SQL updates against the messaging_groups and users tables. Review the SKILL.md file and back up both databases before you let the agent proceed.

The skill does not use the network, according to its listing. Changes it makes are to local database rows and files. Mistakes can affect a running bot, so test with a copy of your data if you can.

• Back up store/messages.db and the v2 central database before starting.
• Do not run the skill on an install you have not backed up.
• Check each AskUserQuestion answer before the agent writes to the database.

Tips for a smooth migration

Keep v1 available until v2 has answered real messages. The skill's own design depends on v1 being paused, not deleted.

If the access policy is strict, make sure the owner row exists first, or you may lock yourself out of the bot.

When you are unsure which sender is which, send a test message from that account and re-run the user query.

• Read logs/nanoclaw.log when a test message gets no reply.
• Use the skill's deselect step to avoid importing senders you do not recognise.
• Record each group's memory migration result in the handoff file.