Migrate Your Agents

Turn the agent you built in a project folder into a shared Archestra agent. Its instructions, skills, MCP servers, and hooks become Archestra resources your team can use.

The migration kit is a skill. Run it in Claude Code, Cursor, OpenCode, or any agent that runs skills. It shows you a plan first, and creates only what you approve.

It reads Claude Code's project files: CLAUDE.md, the .claude/ folder, .mcp.json, and Python tools under tools/. An OpenClaw config goes into the report for you to move by hand. Starting from scratch? Skip this page.

What Moves

In your project	Becomes in Archestra
Instructions, such as `CLAUDE.md`	An agent with those instructions
Skills, slash commands, and scripts	Skills with their bundled files
Subagent instructions	A skill, or a separate agent if you choose. Tool restrictions do not carry over.
MCP servers	MCP catalog entries. Local servers run in Archestra's Kubernetes environment.
`SessionStart`, `PreToolUse`, and `PostToolUse` hooks	Hooks, when compatible
Provider keys	Model provider keys, only for secrets you supply

Everything else, such as OpenClaw runtime settings and other hook events, goes into a follow-up report for you to move by hand.

Run the Migration

You need a coding agent that runs skills and Python 3.10 or newer.

Install the skill:
bash
```
curl -fsSL https://raw.githubusercontent.com/archestra-ai/archestra/main/migration-kit/install.py | python3
```
It goes into the skills folder of each coding agent it finds: Claude Code, Cursor, and OpenCode. For another agent, add - --dest <skills-folder>/migrate-to-archestra after python3.
Open your coding agent in your project's directory and paste:
text
```
Use the migrate-to-archestra skill to migrate this project
into http://localhost:9000. Show me the migration plan before applying it.
```
Use your own Archestra API URL if it is not local (such as https://archestra.example.com). If your deployment requires authentication, create an API key under Account → API Keys and provide it when prompted.
Review the plan. Choose the agents, skills, and MCP servers to create, and who can see each one: you, a team, or the organization.
Approve. The skill creates what you approved and writes a report. It also turns on the organization's skill tools and adds sandbox tools to migrated agents.

Before you share migrated resources, read the report's warnings. The kit hides secrets it finds in config files, but secrets inside instructions or scripts stay there.

Check the Result

Open the new agent under Agents and start a conversation.
Ask it to use one migrated skill.
Fix the report's failures and follow-up items.

Running the migration again skips resources that already exist. Hook tool matchers do not carry over. The migration kit README covers installer options and unsupported cases.