Migrating Complex AI Workflows to awork with MCP

Migrate your extensive, already-structured AI setups to awork without having to rebuild them manually from scratch.

This article is for you if your setup already consists of Markdown files, skills, reference documents, templates, and workflow logic. For these kinds of structures, you can use the awork MCP Server together with the awork Agent Migration Skill to analyze your existing setup and map it into awork.

---

Main Benefits and Use Cases

An MCP-based migration is worth it when your AI setup already looks more like a system than a single prompt.

Typical components include:

• Many Markdown files with different content and responsibilities

• Skills or SKILL.md files as reusable workflows

• Multi-step workflows with different process stages

• Decision rules and quality checks

• Templates and examples for expected outputs

• Authoritative reference documents

• Linked files with dependencies on each other

• External tools or data sources

You could transfer these components individually to awork. But for larger setups, you'd need to clarify first which file serves which purpose and where its content belongs in awork.

The awork Agent Migration Skill supports 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.

Migration follows this process:

Analyze -> Map -> Migrate -> Verify -> Validate

1. Analyzing Your Existing Setup

Before anything gets created in awork, the Migration Skill reads the provided content and creates an inventory.

In doing so, it identifies, among other things:

• The role and purpose of the setup

• 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 with many Markdown files.

30 source files don't automatically become 30 skills. Multiple files can describe a single process together. A single file might mix instructions, reference material, and project-specific information that belong in different places in awork.

2. Mapping Content to the Right awork Concept

Next, the Migration Skill creates a mapping from source to destination.

The key here is mapping content by function and responsibility, not by the original filename.

If a Markdown file mixes multiple topics, its content can therefore be distributed across different awork components.

3. Highlighting Unclear Content for Review

Not every component of an existing setup can be mapped unambiguously.

Possible reasons include:

• Rules contradict each other

• A source is outdated

• A workflow requires a tool that's not 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 silently decide on such cases or simply leave out content.

The goal isn't to migrate as much material as possible. The goal is to take on content you can trust.

4. Creating the awork Setup via MCP

Once the mapping is clarified, the Migration Skill can use the connected awork MCP server to create the corresponding setup.

Depending on the analysis results, it can:

• Create the agent

• Configure the system prompt

• Create new skills

• Import existing SKILL.md files

• Import skill packages with supporting files

• Add reference files

• Reuse or link existing skills

• Verify that the expected configuration was saved

Existing skills can often be reused directly.

A standalone SKILL.md can be imported instead of being rewritten. If a skill package already contains supporting files like references/, scripts/, or assets/, these can stay with the skill.

For other Markdown files, their function is determined first. They're not automatically converted into skills.

Example: A Comprehensive Workflow for Training Content

Let's say you've already built a system for creating content around the German Ausbildungsrahmenplan (vocational training framework).

Over time, you've created:

• Multiple skills

• Numerous Markdown files

• Detailed instructions for content creation

• Course templates

• Examples of accepted results

• Review and validation rules

• A vocational training framework as an authoritative source

A manual migration would mean opening each file, understanding its function, and then rebuilding the structure in awork.

With an MCP-based migration, the existing setup can first be fully analyzed and mapped like this:

Agent System Prompt

Contains the overarching purpose, target audience, boundaries, language, and requirements for the final result.

Skills

Contain reusable workflows, for example:

• Assigning a topic to the vocational training framework

• Developing the course structure

• Creating content

• Performing the final quality check

Skill Reference Files

Contain materials that these workflows reference, for example:

• The relevant vocational training framework

• Templates

• Examples

• Validation criteria

The resulting awork structure can 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 version of a framework, standard, or guideline, that version can remain part of the migrated setup.

However, if the workflow should always use the current official version, just copying an existing file won't be enough. Then you need to establish how the source should be kept current or retrieved before treating the migrated copy as authoritative.

5. Reviewing the Migration and Validating Behavior

After creating the new setup, the Migration Skill reads the configuration back from awork and checks, among other things:

• Whether the agent exists

• 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

• Were verified

• Were not migrated

• Need user testing

The mapping from source to destination is also preserved. This way you can trace where important rules and files ended up.

6. Testing Behavior with Real Tasks

The original setup and the awork agent may differ in the model, available tools, surrounding context, or runtime information delivery.

That's why a final review is important: select several typical tasks where you know what a good result should look like. Run these tasks with the migrated agent.

Test at least:

• A normal 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 the expected outcome.

If something's missing, adjust the responsible skill, instruction, or source instead of just adding more context across the board.

---

Performing Migration with MCP

1. Connect your AI client to the awork MCP Server.

2. Add the awork Agent Migration Skill.

3. Provide the existing skills, Markdown files, and reference materials.

4. Let the Migration Skill analyze the existing setup and suggest a mapping.

5. Review conflicts, unsupported behavior, and open decisions.

6. Approve the migration.

7. Review the resulting migration report.

8. Run the suggested behavior tests with the new awork agent.

---

What MCP-Based Migration Means and What It Doesn't

MCP-based migration does not mean:
Give the AI a folder and automatically get the same system in awork.

Instead, it's about:
The AI analyzes your existing setup, maps it to the appropriate awork structure, automates reliably migratable parts, and makes unclear content visible for review.

You don't have to completely rebuild a mature AI workflow from scratch.

At the same time, migration between two AI environments is more than just copying files. The migration creates a structured starting point in awork. The final validation shows whether the workflow still functions the way you built it.

---

FAQ

Can I migrate my existing Claude or ChatGPT setup?

Yes. Existing, structured content is a good foundation for migration. For more extensive setups, the awork MCP Server can help you analyze the existing structure and map it into awork.

Will it behave the same way afterward?

Not necessarily. Files and instructions can often be transferred. However, behavior can also depend on the model used, available tools, and runtime environment. So test the migrated agent with several typical tasks.

Will all Markdown files become skills?

No. The Migration Skill first determines the function of the respective content. Depending on responsibility, content can belong to the Agent System Prompt, a skill, Skill Reference Files, Agent Files, Workspace Context, or Live awork Context.

Can an existing SKILL.md be imported directly?

Yes. A standalone SKILL.md can be imported instead of being rewritten. Supporting files in references/, scripts/, or assets/ can also be kept in a skill package. Still test them in the new agent since model, context, and available tools may differ.

What happens if something can't be mapped unambiguously?

Content that can't be mapped unambiguously will be marked for review. It won't be automatically guessed at, changed, or left out.