KentiCopilot code migration - best practices

In our demo, you can see how KentiCopilot speeds up codebase migration from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK). This guide is a practical next step.

It builds on the KentiCopilot GitHub documentation and focuses on tips, best practices, and common pitfalls. You will learn what to expect in each migration phase and how to shape the workflow to fit your architecture.

Set your workspace up for success

Let an AI assistant handle the setup. GitHub Copilot, Claude, or a similar assistant can guide you through the installation steps in the KentiCopilot README. If you chose to set up manually and hit an issue (e.g., due to your environment specifics), ask your AI agent to help you recover. It will save you valuable time troubleshooting.
Register the Documentation MCP server in one place only. The KentiCopilot plugins already declare the Documentation MCP server, so you don’t need to add it yourself. If the same server is also declared in your workspace mcp.json, remove or disable that entry. Then open your IDE’s or CLI’s MCP servers list and confirm that only one entry is running. A single active registration guarantees no duplicate instances or unnecessary token usage, regardless of which AI host you use.
Double-check your workspace setup matches our recommendations in the KentiCopilot GitHub documentation.

To avoid any human-error-related oversight, ask your AI assistant to review your project structure and overall setup according to the docs for you.

An example of asking an AI assistant to check your project structure and overall setup of your workspace

Migrate your database to Xperience by Kentico before you start migrating your code. The agent reads the target XbyK database for essential tasks, such as generating content type classes, so the code migration depends on it.

See how KentiCopilot can help you with content audit and migration, including remodeling scenarios.

Understand the migration workflow

There are three main parts to code migration:

Global code – project-wide code that isn’t tied to a single page, such as localization resources, styles, shared business logic, and project startup configuration.
Pages – the controllers, views, layouts, and content retrieval logic behind each page. Pages that use Page Builder also have widgets and sections, which you migrate before the page logic.
Shared components – reusable UI elements embedded directly in views and layouts, such as the header, footer, navigation, and breadcrumbs. These are not Page Builder widgets or sections.

This page is intentionally not a full command walkthrough. Our GitHub documentation provides the complete command flow and prompt syntax.

At a high level, you need to run the global migration first to seed the target project. Then migrate your pages and shared components in the order that suits your project. For pages that use Page Builder, migrate widgets and sections before page logic.

Before you start the code migration, ask the agent to examine your project and produce an overview:

From the codebase: which page types are Page Builder-enabled, which shared components exist, and any component restrictions (for example, which widgets and sections are allowed in a zone).
From the CI serialization files (App_Data/CIRepository, if Continuous Integration is enabled): which specific pages actually use Page Builder and which widget and section types they render. If CI isn’t available, this per-page usage comes from the database instead (the KentiCopilot content audit plugin can export it).

This overview helps you decide the order in which to migrate your pages and components.

Example output from an AI agent mapping out which page types use the Page Builder feature

What to verify after each phase

We recommend you only move forward once the current phase is stable:

After global migration: the project compiles, startup runs without errors, and content type classes exist for every content type in your solution.
After each page migration: the page renders correctly and the Page Builder tab appears on pages that need it.

Consider enabling Page Builder for almost all migrated page content types, even if the KX13 original didn’t use it. This keeps the option of using page templates open later. If a page is migrated without a Page Builder template registration, it can be difficult to convert afterward.
After component migration: shared components render correctly across all pages that use them and have been migrated. The agent visually compares each component against the KX13 original using Playwright, and it skips components it has already migrated, so you can re-run /migrate-shared-component safely.

Troubleshooting

The agent attempts to resolve build errors during migration, so most issues are handled for you. If something still does not build or render correctly, ask the agent to identify the root cause and fix it before you continue. If you’re unsure what to do next, ask the agent to propose the next best migration step based on your current project state.

If a migrated page’s look and feel doesn’t match the KX13 original, run /migrate-page-visual. This skill uses Playwright to compare the migrated page against the original and realign the styling.

Enforce a target architecture

The default run (lift-and-shift) produces working code with no upfront configuration, but it also lets the agent make structural decisions for you: content retrieval logic lands in controllers, components go into flat directories, and naming follows agent defaults. For production projects, you usually want your own conventions, such as feature folders, shared services, and consistent naming. The skills are architecture-agnostic by design, so you can shape the output by giving the agent project-specific instruction files.

Generate instructions from a reference project

To quickly create instructions, point the agent at a well-structured XbyK project and have it generate your instruction files from that project’s patterns. Suitable reference projects, in order of preference:

Your own baseline project: the best option if you already have a well-structured XbyK solution. It reflects your real conventions rather than a generic ideal.
The open-source Community Portal repo: our recommended alternative for larger, multichannel projects with many customizations. Its Operations folder shows an advanced CQRS and query-caching approach worth modeling content retrieval on.
The Training guides repo (finished branch): a cleaner, simpler structure for smaller projects.

An example prompt to generate the files:

Text

Prompt example: generate instruction files from a reference project


Review the structure and patterns in [reference project]. Generate instruction files that guide code generation for my project, covering: solution and project structure and dependencies; feature organization; content retrieval; the layering from content types to domain models, repositories, services, controllers, and view models; naming conventions; service registration; C# style; and the docs the agent should consult. Where it helps, split the guidance into focused files scoped with applyTo, each covering a single concern.

Based on your needs and the complexity of your project, the result can be a small set of focused files or a single document. For example, a project-structure instruction file might spell out the folder layout you want the agent to follow:

Text

Sample from a generated project-structure instruction file


src/
├── DemoProject.Entities/   # Interfaces and generated content type classes
├── DemoProject.Core/       # Domain models and business logic, no infrastructure
├── DemoProject.Web/        # ASP.NET Core app: UI + infrastructure
└── DemoProject.Admin/      # Admin customizations

Web/Features/Blog/
├── BlogPostPageController.cs   # Thin: injects a service, returns a view
├── Repositories/               # Data access, returns domain models
├── Services/                   # Orchestrates repositories + domain logic
├── ViewModels/
└── Views/

What your instruction files should cover

Whether you keep everything in one file or split it across several, aim to cover:

Project and solution structure: which project owns what, and how they reference each other.
Feature organization: how code is grouped, such as feature folders that keep a feature’s controller, services, and views together.
Content retrieval: a consistent approach, such as a shared retriever service and repositories, so queries aren’t scattered.
Layering and responsibilities: the path from content types to domain models, repositories, application services, thin controllers, and view models.
Mapping: where conversions between generated types, domain models, and view models happen.
Naming conventions: files, classes, and namespaces.
Dependency injection and startup: how services get registered, such as per-feature extension methods.
C# style preferences: the conventions to apply consistently, such as records for DTOs, primary constructors for dependency injection, async usage, and error handling.
Documentation references: the links the agent should rely on.
Testing: how and where tests are organized.

Content remodeling during migration

You reshape your content model during the content migration, before you migrate code. The content migration plugin handles this and supports transformations such as:

Merging, splitting, or renaming classes
Renaming fields, converting values, or patching data types and form controls
Extracting reusable field schemas shared across content types
Converting source pages and content into reusable Content hub items

Because code migration reads your migrated XbyK database, it works from the remodeled structure instead of just the original KX13 codebase.

Simple remaps are usually reliable. More involved remodeling can work well too. However, the more your target model diverges from the source, the more important review discipline becomes.

The quality of the migration output depends on the model you use. A more capable LLM makes better architectural decisions and handles edge cases more reliably.

Known limitations and useful links

The skills are a starting point:

The migration skills are intentionally general-purpose. They’re meant to be extended for your specific project: add context, adjust prompts, and introduce project-specific patterns. The KentiCopilot repository is the right place to start.

Useful links:

Some of these resources are referenced above; others are additional material for deeper context and practical guidance:

Upgrade overview – End-to-end upgrade phases and decision points.
Upgrade FAQ – Common migration questions, constraints, and practical recommendations.
KentiCopilot content audit and migration – How to utilize KentiCopilot to help assess and migrate content, including remodeling scenarios.
KentiCopilot parent repository – Official source for plugins, setup details, and ongoing updates.
Community Portal repository – Official open-source Xperience by Kentico project with advanced, real-world implementation patterns; a strong reference for larger, multichannel architectures.
Training guides repository – Official Xperience by Kentico sample-learning project with a clean, production-like baseline; a good reference for smaller solutions and straightforward structure patterns.
Kentico AI development hub – Broader AI resources for developers, updates, and guidance beyond this migration flow.