Guide · Agent skill

How to use the migrate-slack-agents skill for NanoClaw

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The migrate-slack-agents skill is an agent skill for NanoClaw, an agent setup that talks to Slack. It moves an install that uses one shared classic Slack bot to a separate, named Slack app for each existing agent group, keeping each agent's identity, workspace, memory and routing. This guide explains what the skill does, how to install it, how to ask your agent to run it, and what it needs and touches, so you can decide whether to migrate or stay on classic Slack.

Migrate Classic Slack Agentsnanocoai/nanoclaw · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.
2Open your NanoClaw project root. Start your agent from the NanoClaw project root, since the skill's queries and file checks are run from there.
3Ask for the migration check. Tell the agent in plain language that you want to migrate your classic Slack setup to one Slack app per agent. The skill starts by detecting classic state.
4Review the detection result. If the install is not in classic state, the skill stops and reports that nothing needs migrating. If it is, you see the signals it found, with token values kept out of view.
5Choose migrate or stay on classic. You are offered the choice before anything changes. Staying on classic makes no changes and acknowledges the update requirement; migrating continues.
6Confirm the dry-run map. Check the table of agent groups, slugs, old messaging-group ids, wiring rows and proposed slack-<slug> surfaces, rename any duplicate display names, and confirm the full mapping.
7Let the companion payloads install. The skill refreshes the Slack channel skill, fetches the channels branch without merging, and applies the slack-a2a-rooms and slack-agent-flow payloads in order. Provisioning authority and cutover follow in the rest of the file.

What the migrate-slack-agents skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells your coding agent how to carry out a specific task. This one covers a single job: turning every agent group wired through the classic Slack adapter into a named slack-<slug> bot without replacing the agent group.

It is an operator-guided, resumable data migration, not a rebuild. The file says it never creates an agent group and never edits an agent workspace. It also offers a choice first: staying on classic Slack is a valid outcome, and classic single-bot Slack remains fully supported.

Detects whether the install has classic shared-bot Slack state and stops cleanly if it does not.
Offers the choice to migrate or stay on classic before changing anything.
Inventories every classic Slack surface and its wiring, then proposes a slug per agent group.
Shows a dry-run table and asks you to confirm the full map before continuing.
Keeps classic rows, credentials and the shared Slack app available for rollback until you approve cutover.

How to install the migrate-slack-agents skill

Download the skill ZIP from this page and unzip it. You can put the skill in either of two places: your user-level skills folder at ~/.claude/skills/, or a single project's .claude/skills/ folder if you want it only for one NanoClaw checkout.

If you use the Claude apps instead, you can upload the ZIP under Settings → Capabilities → Skills.

Personal use across projects: unzip into ~/.claude/skills/.
Single project only: unzip into the project's .claude/skills/ folder.
Claude apps: upload the ZIP under Settings → Capabilities → Skills.

How to trigger the skill with natural requests

You do not need a special command. Describe what you want in plain language, for example asking the agent to migrate your classic Slack setup to one Slack app per agent, or to check whether your Slack setup needs migrating. The skill is also meant to run when /update-nanoclaw shows the Slack agents requirement, and you can run it standalone any time later.

The file also names /migrate-slack-agents as the manual invocation for later use.

Run it from the NanoClaw project root, because every query is run from there.
If you only want to record that you are staying on classic, say so; the skill then acknowledges the update requirement and stops.

What the skill checks and shows you before any change

Migration only starts when the install shows all the classic signals. The skill reads src/channels/index.ts for the Slack import, and checks .env for a non-empty SLACK_BOT_TOKEN plus either SLACK_APP_TOKEN or SLACK_SIGNING_SECRET, reporting presence without printing values. It then runs a read-only query against the central database through scripts/q.ts.

Next it captures every classic surface: agent groups, messaging groups, wiring rows, unknown-sender policy and destinations. It proposes one unique slug per agent group, including the group commonly called master, and presents a dry-run table. If two groups share a Slack display name, the skill flags it so you can rename before provisioning, which is free at that stage.

If the classic signals are missing and there is no partial state, the skill stops with a no-op message: nothing to migrate.
If only some signals exist, the skill makes no changes and reports the partial state.
If every wired group already has complete named coverage, the skill reports the migration as already complete.
Nothing changes until you confirm the entire mapping.

pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.id, mga.id, mga.agent_group_id FROM messaging_groups mg JOIN messaging_group_agents mga ON mga.messaging_group_id=mg.id WHERE mg.channel_type='slack' AND mg.instance='slack' ORDER BY mg.id, mga.agent_group_id"

Install the current Slack agents payloads

Before provisioning, the skill runs /update-skills for the installed Slack channel and requires a successful, refreshed result. It then resolves the remote that points at nanocoai/nanoclaw, rather than assuming origin, and fetches the channels branch. It does not merge that branch.

From the fetched branch it copies the skill-owned files for slack-a2a-rooms and then slack-agent-flow, applying each companion's own steps in that order. It does not continue unless both report fully applied and their own build or tests pass.

This step uses the network to fetch from the nanocoai/nanoclaw remote.
The fetch is never merged into your branch.

source setup/lib/channels-remote.sh
channels_remote="$(resolve_channels_remote)"
git fetch "$channels_remote" channels

Safety notes: scripts, network and what the skill never does

This skill runs scripts and uses the network, and it touches the central database, environment credentials and Slack app configuration. Treat it as a change to your live setup and read the dry-run table carefully before confirming.

The file sets hard limits. It never calls create_agent or ncl groups create, never changes an agent group id, never writes under groups/<folder>/, and never prints token values. Classic rows, credentials and the shared Slack app stay in place for rollback until you explicitly approve cutover. The later phases of the full file cover provisioning authority and cutover; this guide covers the detection, choice, inventory and payload steps shown in the source.

Never prints token values; only key names and masked presence are shown.
Never merges the channels branch; only skill-owned files are copied.
Requires you to approve cutover explicitly.

What people use it for

Moving several agents that share one classic Slack bot to a separate, named Slack app per agent while keeping their existing workspaces and memory.
Responding to the Slack agents requirement that /update-nanoclaw raises, by reviewing the change and deciding whether to migrate.
Keeping the classic single-bot setup and recording that choice so the update requirement is acknowledged.
Checking a partially migrated install to find out which Slack surfaces are still classic and which are complete.

Frequently asked questions

Is the migrate-slack-agents skill free?

The skill is published under the MIT licence, as stated on this page. The page does not list any prices, so check the NanoClaw repository for its terms if you need more detail.

What do I need before I run migrate-slack-agents?

You need a NanoClaw project checkout with data/v2.db and the scripts/q.ts wrapper, pnpm and tsx, and git with access to the nanocoai/nanoclaw remote. You also need existing Slack bot tokens in .env and permission in your Slack workspace to create and configure additional Slack apps.

Does the skill delete my existing agents or Slack setup?

No. The file says it never creates an agent group, never changes an agent group id, and never edits an agent workspace. It keeps classic rows, credentials and the shared Slack app available for rollback until you approve cutover.

Can I stay on classic Slack instead of migrating?

Yes. The file states that classic single-bot Slack remains fully supported, and that staying on classic is a valid outcome that also satisfies the update requirement.

What should I do if the skill says there is nothing to migrate?

That message means the install does not have the classic shared-bot Slack state, so the skill stops without changes. If you expected migration, check that src/channels/index.ts has the Slack import and that .env has the Slack tokens the skill looks for.

How is this different from a manual Slack app setup?

This skill is a guided, resumable migration that inventories your existing wiring, proposes a map, and waits for your confirmation before changing anything. It is designed for an existing classic install rather than a fresh build, so it is not a quick one-command change.

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 run several NanoClaw agents through one classic Slack bot and want each agent to have its own named Slack identity, and you are comfortable reviewing a dry-run table before changes. If you have no NanoClaw install or Slack integration, or you want a quick one-command change, pick something else or stay on classic Slack, which the file says remains supported.

Download the skill