Migrate complex AI workflows to awork with MCP
Migrate AI workflows to awork using the MCP Server and Agent Migration Skill to automatically map your existing skills, files, and tools.
Migrate extensive, already-structured AI setups to awork without having to rebuild them manually from scratch.
This guide is for you if you want to recreate an existing workflow with multiple skills, files, or tools in your awork account. For setups like these, you can use the awork MCP Server together with the awork Agent Migration Skill to analyze your existing setup and map it to awork.
Connect your AI client to the awork MCP Server and sign in with your own awork account. The MCP Server uses your existing permissions. Check whether your AI client supports the necessary write actions and whether you're allowed to create the components in awork. If your connection is read-only, ask it to suggest a mapping and create the components manually.
Planning to make the switch for multiple teams or your entire organization? Contact awork Support. We'll work with you to find the right migration path.
👉 If your current AI setup consists of just a few instructions and knowledge files, see the guide Migrate AI context to awork.
Main benefits and use cases
An MCP-powered migration is useful when your AI setup is more like a system than a single prompt.
Typical components include:
-
Many Markdown files with different content and responsibilities
-
Skills or
SKILL.mdfiles that describe reusable workflows -
Multi-step workflows with different process steps
-
Decision rules and quality checks
-
Templates and examples of expected results
-
Authoritative reference documents
-
Linked files that depend on one another
-
External tools or data sources
You could transfer these components to awork one by one. But with larger setups, you'd first need to work out what each file does and where its content belongs in awork.
The awork Agent Migration Skill helps you with exactly these two steps: analysis and mapping.
How migration with MCP works
Migration doesn't try to copy your original folder structure file by file. The goal is to preserve the underlying workflow.
That's why migration follows this process:
Analyze → Map → Migrate → Verify → Validate
1. Analyze the existing setup
Before anything is created in awork, the Migration Skill reads the content you provide and creates an inventory.
It identifies, among other things:
-
The setup's role and purpose
-
Its target audience and language
-
Required inputs
-
Workflow steps and decision paths
-
Output requirements
-
Tools and external systems
-
Authoritative references
-
Templates and examples
-
Quality checks and stop conditions
-
Conflicting or duplicate rules
This is especially important when you have many Markdown files.
30 source files don't automatically become 30 skills. Several files may describe a process together. On the other hand, a single file may mix instructions, reference materials, and project-specific information that belong in different places in awork.
2. Map content to the right awork concept
Next, the Migration Skill creates a source-to-target mapping.
| Existing content | Destination in awork |
|---|---|
| Role, goal, boundaries, and output requirements | Agent System Prompt |
Existing SKILL.md files or skill packages | Skill |
| Reusable workflows | Skill |
| Extensive references, standards, examples, and templates for a workflow | Skill reference files |
| Knowledge needed by only one agent | Agent files |
| Shared company knowledge | Workspace Context |
| Current project-specific information | Live awork context |
| Actions in external systems | awork or connected tools |
The key is to map content based on its function and responsibility, not its original filename.
So if a Markdown file mixes several topics, its content may be split across different awork components.
3. Flag unclear content for review
Not every part of an existing setup can be mapped unambiguously.
Possible reasons include:
-
Rules conflict
-
A source is outdated
-
A workflow requires a tool that isn't available in the target setup
-
A behavior depends on the original AI environment
-
It's unclear which version of an authoritative document should be used
The Migration Skill shouldn't make decisions about these cases without telling you or simply leave content out.
Content that can't be mapped reliably will be flagged for review.
The goal isn't to migrate as much material as possible. It's to transfer the content you can trust.
4. Create the awork setup through MCP
Once the mapping has been reviewed, the Migration Skill can use the connected awork MCP server to create the corresponding setup.
Depending on the analysis, it can:
-
Create the agent
-
Configure the System Prompt
-
Create new skills
-
Import existing
SKILL.mdfiles -
Import skill packages with supporting files
-
Add reference files
-
Reuse or link existing skills
-
Check whether the expected configuration has been saved
Existing skills can often be reused directly.
A standalone SKILL.md can be imported instead of rewritten. If a skill package already contains supporting files such as references/, scripts/, or assets/, those files can stay with the skill.
Other Markdown files are first assessed based on their function. They aren't automatically turned into skills.
Example: An extensive workflow for training content
Suppose you've already built a system for creating content about the German vocational training framework plan (Ausbildungsrahmenplan).
Over time, it has grown to include:
-
Several skills
-
Numerous Markdown files
-
Detailed instructions for creating content
-
Course templates
-
Examples of accepted results
-
Review and validation rules
-
A vocational training framework plan as an authoritative source
Migrating everything manually would mean opening each file, understanding its function, and then rebuilding the structure in awork.
With an MCP-powered migration, the existing setup can first be analyzed in full and mapped, for example, as follows:
Agent System Prompt
Contains the overall purpose, target audience, boundaries, language, and requirements for the final result.
Skills
Contain reusable workflows, for example:
-
Mapping a topic to the vocational training framework plan
-
Developing the course structure
-
Creating content
-
Carrying out the final quality check
Skill reference files
Contain materials used by these workflows, for example:
-
The relevant vocational training framework plan
-
Templates
-
Examples
-
Validation criteria
The resulting awork structure may therefore look different from the original folder structure. The responsibilities of the original workflow are still preserved.
How to handle changing reference materials
Authoritative sources need special attention.
If your existing workflow deliberately uses a specific edition of a framework, standard, or policy, that edition can remain part of the migrated setup.
However, if the workflow should always use the latest official version, copying an existing file isn't enough. Before treating the migrated copy as authoritative, you need to decide how the source will be kept up to date or retrieved.
If multiple versions are available and it's unclear which one to use, the Migration Skill should flag this for review instead of automatically selecting a version.
5. Review the migration and validate behavior
After creating the new setup, the Migration Skill reads the configuration back from awork and checks, among other things:
-
Whether the agent is present
-
Whether the expected skills were created or linked
-
Whether the correct instructions were saved
-
Whether reference files are present
-
Whether any migration steps failed
The migration report then shows which components were:
-
Created
-
Verified
-
Not migrated
-
Require user testing
The mapping from source to destination is also preserved, so you can see where important rules and files ended up.
6. Test behavior with real tasks
A technically correct migration doesn't automatically mean the AI will behave identically.
The original setup and the awork agent may differ in the model, the tools available, the surrounding context, or how information is provided at runtime.
That's why a final review is important: choose several typical tasks where you know what a good result should look like, then run them with the migrated agent.
Test at least:
-
A typical task
-
An important workflow branch
-
A task with missing inputs
-
A task with authoritative reference material
-
A task with strict output requirements
Compare the results with what you expected.
If something is missing, adjust the relevant skill, instruction, or source instead of adding more context across the board.
👉 Learn more about the reasoning behind this approach in Migrating AI context: 7 principles
Migrate with MCP
-
Connect your AI client to the awork MCP Server.
-
Add the awork Agent Migration Skill.
-
Provide your existing skills, Markdown files, and reference materials.
-
Have the Migration Skill analyze your existing setup and suggest a mapping.
-
Review conflicts, unsupported behavior, and open decisions.
-
Approve the migration.
-
Review the resulting migration report.
-
Run the suggested behavior tests with your new awork agent.
Tip: If you have a very large setup, start with a representative workflow. It should include several important elements, such as a skill, multiple reference files, and relevant decision logic. This lets you check that the mapping and behavior make sense before migrating the rest.
Review your migrated workflow
✅ Your AI client is connected to your awork account and can create the required components. If not, create them manually.
✅ You've reviewed the mapping. Open questions and unsupported steps are documented.
✅ The intended agents, skills, and references are in place. The required tools, scripts, and external connections work in the new setup.
✅ The workflow works in a standard case and responds appropriately when inputs are missing or a source is unavailable.
✅ The people running the workflow have access to the required sources and features.
What MCP-assisted migration means, and what it doesn't
MCP-assisted migration does not mean:
Give the AI a folder and automatically get the same system in awork.
Instead, it means:
The AI analyzes your existing setup, maps it to the right awork structure, reliably automates the parts that can be migrated, and flags unclear content for review.
So you don't have to rebuild a mature AI workflow from scratch.
At the same time, migrating between two AI environments involves more than copying files. The migration creates a structured starting point in awork. Final validation shows whether the workflow still works the way you designed it to.
FAQ
Can I migrate my existing Claude or ChatGPT setup?
Yes. Existing structured content is a good starting point for migration. For larger setups, the awork MCP Server can help you analyze your existing structure and map it to awork.
Will it behave exactly the same afterward?
Not necessarily. Files and instructions can often be transferred. However, behavior can also depend on the model, the available tools, and the runtime environment. So test your migrated agent with several typical tasks.
Do all Markdown files become skills?
No. The Migration Skill first determines the purpose of each piece of content. Depending on its role, content may belong in the agent system prompt, a skill, skill reference files, agent files, the workspace context, or the live awork context.
Can I import an existing SKILL.md directly?
Yes. You can import a standalone SKILL.md instead of rewriting it. Supporting files in references/, scripts/, or assets/ can also be kept in a skill package. Still, test them with the new agent, since the model, context, and available tools may differ.
What happens if something can't be mapped clearly?
Content that can't be mapped clearly is flagged for review. It won't be guessed, changed, or left out automatically.
