Plans and executes a migration from AEM 6.x (on-prem or managed services) to AEM as a Cloud Service — readiness assessment, code refactoring, content transfer, identity, cutover and risk.
When agents use itUse this whenever the user mentions moving to AEMaaCS; runs or reads a Best Practices Analyzer report or uses Cloud Acceleration Manager; asks about the Content Transfer Tool, extraction and ingestion, top-ups, migration sets, user mapping or Group Migration, Bulk Import, Repository Modernizer, Index Converter, Dispatcher Converter or the AEM Modernization Tools; needs to restructure into ui.apps/ui.content/ui.config, move /etc to /conf, convert sling:OsgiConfig nodes to .cfg.json, replace static templates, Classic UI dialogs or DAM Update Asset workflows; or estimates effort, content freeze and go-live. Also use it for the upgrade-versus-migrate decision, including AEM 6.5 LTS as the alternative.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a github-copilot
# or with the org installer (adds .github/skills/aem-cloud-migration):
npx -y github:AGCO-Global/org-skills add skill aem-cloud-migration
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-devops-skills plugin, which bundles all AEM / DevOps skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-devops-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-cloud-migration folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
A migration is a code refactor, plus a content move, plus an operating-model change — and the content move is the one you cannot undo. Assess with the tools, refactor to Cloud rules before moving any content, rehearse the transfer at production volume, and cut over with an enforced freeze and a measured top-up. Everything else is negotiable; those four are not.
1. Decide first
Question
Default
Change when
Migrate or stay
Migrate to Cloud Service
A hard constraint (regulated hosting, unsupported native dependency, unfunded rework) → AEM 6.5 LTS, with the constraint and a review date recorded
Order of work
Code refactor first, content second
Never move content before the project builds green in Cloud Manager
Refactor or rewrite a component
Refactor to a Core Components proxy
The component exists only because Core did not, and now does → retire it
Site tree paths
Keep them
Changing paths during the migration doubles the validation work and breaks top-ups — do it as a separate project
Assets: CTT or Bulk Import
CTT for assets the site references
A large standalone library with no version history to keep → Bulk Import
Publish content
Repopulate by publishing from the migrated author
It is also the end-to-end test of the new publishing chain
Author identity
Adobe IMS product profiles mapped to AEM groups, set up before UAT
Passwords are never migrated, so there is no other option
Freeze
Enforced by permissions, with a written change log
An email to the authoring team is not a freeze
Rehearsal count
Two, the second at production volume
One rehearsal tells you the process works, not how long it takes
2. Phases
Phase
Output
Exit criteria
Discovery
BPA report in Cloud Acceleration Manager, plus an inventory of sites, components, integrations, workflows, repository size and users
Every finding categorised refactor / replace / retire, with an effort figure
Code refactor
A Cloud-compatible project building green in Cloud Manager
Zero critical code-quality findings; deploys to dev; feature parity tested
Transfer rehearsal
Timed extraction and ingestion to stage
Durations known, failures understood, user mapping validated
UAT and performance
Signed-off stage with migrated content
Business sign-off, load test on stage, redirect and SEO checks
Cutover
Freeze → final top-up → DNS/CDN switch
Smoke tests pass; source kept read-only as the fallback
Hypercare
Monitoring, fixes, decommission plan
Stable error rates; source decommissioned on schedule
3. Assessment
Run the Best Practices Analyzer on a production clone (not a dev instance — the findings track the content and code that actually exists) and upload the report to Cloud Acceleration Manager, which groups findings by category and importance and tracks readiness through the implementation phase.
Treat BPA as a floor. It does not run your code, so it cannot see admin sessions hidden behind a utility class, file-system writes inside a library, threads that outlive a pod, or hardcoded /etc paths. references/refactor-checklist.md has the grep list that finds those, and the full area-by-area refactor table.
The six areas that dominate the estimate on almost every project: project restructure into ui.apps/ui.content/ui.config, /etc → /conf, sling:OsgiConfig → .cfg.json, static templates → editable templates, custom DAM workflows → processing profiles, and admin sessions → service users. Everything else is a long tail.
Custom Oak indexes are converted to type="lucene" and renamed to the Cloud grammar — that is exactly what the Index Converter does. The naming rule is in oak-index-naming.md in ../../development/aem-backend-development/references/.
4. Content transfer
Install the Content Transfer Tool on the source author; create a migration set in CAM and copy the extraction key.
Extraction to Adobe-managed staging (pre-copy blobs ahead of the freeze for large stores), then ingestion to the target — first with wipe, then top-ups without.
Purge versions, audit logs and workflow instances on the source first. Transfer time scales with repository size, and most 6.x repositories are mostly history.
Top-ups respect updates and deletes made in the source. Moves, renames and anything whose path changed during the refactor still need a validation pass that compares counts per tree.
Users and groups referenced by migrated content come along; unreferenced groups need the separate Group Migration step. Passwords do not migrate — Admin Console product profiles and group mapping happen before UAT, so testers exercise real permissions.
Large standalone asset libraries go through Bulk Import from Azure Blob, Amazon S3, Google Cloud Storage, Dropbox or OneDrive. Configure processing profiles on the target before ingesting, or the library is reprocessed twice.
Command surface, the CTT-vs-Bulk-Import table, identity details and the cutover runbook are in references/content-transfer.md.
5. Cutover and risk
T-6w Rehearsal 1 to stage, timed T-3w Rehearsal 2 at production volume + UAT
T-1w Code freeze on source T-2d Content freeze (permissions, not email)
T-1d Final top-up, publish, warm T-0 DNS/CDN switch, smoke tests, watch 404s
T+2w Hypercare; source read-only, then decommission
Risk
Impact
Mitigation
Transfer exceeds the freeze window
High
Rehearse at full size; purge history; pre-copy blobs
Hidden admin sessions or file-system writes
High
Manual grep audit beyond BPA; deploy to an RDE early
Index mismatch → slow queries after go-live
High
Index Converter plus query plans checked on stage
Integrations blocked by egress rules
High
Advanced Networking requested weeks ahead, configured before UAT
Asset reprocessing backlog
Medium
Processing profiles first; stagger ingestion
Identity gaps found during UAT
Medium
IMS profiles and group mapping before UAT, not after
Scope them separately at discovery; they are not part of a Sites migration
Deliverable format
## Readiness assessment
Source: AEM <version> <on-prem|managed> · Repo <GB> · Assets <n> · Sites <n> · Locales <n>
BPA summary: <critical/major counts by category>
| Finding | Category | Decision (refactor/replace/retire) | Effort (d) | Owner |
## Migration plan
Phases with dates and exit criteria; rehearsal schedule; freeze window with enforcement
Content transfer: migration sets, measured durations, top-up and validation plan
Identity: IMS profiles → AEM groups, Group Migration, UAT roles
Cutover runbook: step · owner · duration · verification · go/no-go
Risk table with mitigations and the rollback position (source read-only until <date>)
Checklist
BPA run on production-like content and every finding categorised with an effort figure
Manual audit done for admin sessions, file writes, threads and /etc literals
Project builds green in Cloud Manager before any content moves
Indexes converted to lucene and renamed to the Cloud grammar
Two rehearsals, the second at production volume, both timed
Top-up validation compares counts per tree, including moves and renames
IMS product profiles and group mapping done before UAT
Processing profiles configured before any asset ingestion
Advanced Networking requested early if any integration needs a fixed egress
Freeze enforced by permissions, with a change log
Cutover runbook has an owner and a verification step per line
Forms, Screens and user-generated content scoped separately
Anti-patterns
Moving content before the code builds green → the target keeps changing under the content you just moved.
Treating BPA as the whole assessment → add the grep audit; BPA does not run your code.
Lifting /etc designs, static templates and Classic dialogs "to fix later" → later never comes, and Cloud Service does not support them.
Porting custom DAM Update Asset steps → processing profiles, with genuinely custom work as post-processing or an Asset Compute worker.
One untimed transfer on go-live weekend → two rehearsals, the second at volume.
Migrating years of versions and audit logs → purge first; it is the cheapest hour of the project.
A freeze announced by email → enforce it with permissions and keep a change log.
Discovering the Advanced Networking lead time in go-live week → request it at discovery.
Assuming Forms or Screens come along with Sites → scope them separately.
Go deeper
references/refactor-checklist.md — the full area-by-area refactor table, the grep list for what BPA cannot see, products that do not migrate, and 6.5 LTS as the alternative.
references/content-transfer.md — CTT step by step, top-up semantics, identity and Group Migration, Bulk Import sources and the CTT comparison, the cutover runbook, freeze enforcement.
oak-index-naming.md in ../../development/aem-backend-development/references/ — the index grammar the Index Converter targets.
Sibling skills: aem-cloud-manager for the pipelines the refactored project ships through, aem-architecture for the target design, aem-dispatcher for the converted dispatcher config, aem-assets for processing profiles.
---
name: aem-cloud-migration
description: >
Plans and executes a migration from AEM 6.x (on-prem or managed services) to AEM as a Cloud Service — readiness assessment, code refactoring, content transfer, identity, cutover and risk. Use this whenever the user mentions moving to AEMaaCS; runs or reads a Best Practices Analyzer report or uses Cloud Acceleration Manager; asks about the Content Transfer Tool, extraction and ingestion, top-ups, migration sets, user mapping or Group Migration, Bulk Import, Repository Modernizer, Index Converter, Dispatcher Converter or the AEM Modernization Tools; needs to restructure into ui.apps/ui.content/ui.config, move /etc to /conf, convert sling:OsgiConfig nodes to .cfg.json, replace static templates, Classic UI dialogs or DAM Update Asset workflows; or estimates effort, content freeze and go-live. Also use it for the upgrade-versus-migrate decision, including AEM 6.5 LTS as the alternative.
metadata:
technology: AEM
type: migration
---
# AEM Cloud Service Migration
> **Targets:** AEM 6.4/6.5 (and 6.5 LTS) → AEM as a Cloud Service 2026.x · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/migration-journey/migration-journey
A migration is a code refactor, plus a content move, plus an operating-model change — and the content move is the one you cannot undo. Assess with the tools, refactor to Cloud rules **before** moving any content, rehearse the transfer at production volume, and cut over with an enforced freeze and a measured top-up. Everything else is negotiable; those four are not.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Migrate or stay | Migrate to Cloud Service | A hard constraint (regulated hosting, unsupported native dependency, unfunded rework) → **AEM 6.5 LTS**, with the constraint and a review date recorded |
| Order of work | Code refactor first, content second | Never move content before the project builds green in Cloud Manager |
| Refactor or rewrite a component | Refactor to a Core Components proxy | The component exists only because Core did not, and now does → retire it |
| Site tree paths | Keep them | Changing paths during the migration doubles the validation work and breaks top-ups — do it as a separate project |
| Assets: CTT or Bulk Import | CTT for assets the site references | A large standalone library with no version history to keep → Bulk Import |
| Publish content | Repopulate by publishing from the migrated author | It is also the end-to-end test of the new publishing chain |
| Author identity | Adobe IMS product profiles mapped to AEM groups, set up before UAT | Passwords are never migrated, so there is no other option |
| Freeze | Enforced by permissions, with a written change log | An email to the authoring team is not a freeze |
| Rehearsal count | Two, the second at production volume | One rehearsal tells you the process works, not how long it takes |
## 2. Phases
| Phase | Output | Exit criteria |
|---|---|---|
| **Discovery** | BPA report in Cloud Acceleration Manager, plus an inventory of sites, components, integrations, workflows, repository size and users | Every finding categorised refactor / replace / retire, with an effort figure |
| **Code refactor** | A Cloud-compatible project building green in Cloud Manager | Zero critical code-quality findings; deploys to dev; feature parity tested |
| **Transfer rehearsal** | Timed extraction and ingestion to stage | Durations known, failures understood, user mapping validated |
| **UAT and performance** | Signed-off stage with migrated content | Business sign-off, load test on stage, redirect and SEO checks |
| **Cutover** | Freeze → final top-up → DNS/CDN switch | Smoke tests pass; source kept read-only as the fallback |
| **Hypercare** | Monitoring, fixes, decommission plan | Stable error rates; source decommissioned on schedule |
## 3. Assessment
- Run the **Best Practices Analyzer** on a production clone (not a dev instance — the findings track the content and code that actually exists) and upload the report to **Cloud Acceleration Manager**, which groups findings by category and importance and tracks readiness through the implementation phase.
- Treat BPA as a floor. It does not run your code, so it cannot see admin sessions hidden behind a utility class, file-system writes inside a library, threads that outlive a pod, or hardcoded `/etc` paths. `references/refactor-checklist.md` has the grep list that finds those, and the full area-by-area refactor table.
- The six areas that dominate the estimate on almost every project: project restructure into `ui.apps`/`ui.content`/`ui.config`, `/etc` → `/conf`, `sling:OsgiConfig` → `.cfg.json`, static templates → editable templates, custom DAM workflows → processing profiles, and admin sessions → service users. Everything else is a long tail.
- Custom Oak indexes are converted to `type="lucene"` and renamed to the Cloud grammar — that is exactly what the **Index Converter** does. The naming rule is in `oak-index-naming.md` in `../../development/aem-backend-development/references/`.
## 4. Content transfer
1. Install the **Content Transfer Tool** on the source author; create a **migration set** in CAM and copy the extraction key.
2. **Extraction** to Adobe-managed staging (pre-copy blobs ahead of the freeze for large stores), then **ingestion** to the target — first with wipe, then top-ups without.
3. Purge versions, audit logs and workflow instances on the source first. Transfer time scales with repository size, and most 6.x repositories are mostly history.
4. **Top-ups respect updates and deletes** made in the source. Moves, renames and anything whose path changed during the refactor still need a validation pass that compares counts per tree.
5. Users and groups referenced by migrated content come along; unreferenced groups need the separate **Group Migration** step. Passwords do not migrate — Admin Console product profiles and group mapping happen before UAT, so testers exercise real permissions.
6. Large standalone asset libraries go through **Bulk Import** from Azure Blob, Amazon S3, Google Cloud Storage, Dropbox or OneDrive. Configure processing profiles on the target *before* ingesting, or the library is reprocessed twice.
Command surface, the CTT-vs-Bulk-Import table, identity details and the cutover runbook are in `references/content-transfer.md`.
## 5. Cutover and risk
```
T-6w Rehearsal 1 to stage, timed T-3w Rehearsal 2 at production volume + UAT
T-1w Code freeze on source T-2d Content freeze (permissions, not email)
T-1d Final top-up, publish, warm T-0 DNS/CDN switch, smoke tests, watch 404s
T+2w Hypercare; source read-only, then decommission
```
| Risk | Impact | Mitigation |
|---|---|---|
| Transfer exceeds the freeze window | High | Rehearse at full size; purge history; pre-copy blobs |
| Hidden admin sessions or file-system writes | High | Manual grep audit beyond BPA; deploy to an RDE early |
| Index mismatch → slow queries after go-live | High | Index Converter plus query plans checked on stage |
| Integrations blocked by egress rules | High | Advanced Networking requested **weeks** ahead, configured before UAT |
| Asset reprocessing backlog | Medium | Processing profiles first; stagger ingestion |
| Identity gaps found during UAT | Medium | IMS profiles and group mapping before UAT, not after |
| Content drift during the freeze | High | Permission-enforced freeze, change log, top-up validation |
| Forms or Screens assumed in scope | High | Scope them separately at discovery; they are not part of a Sites migration |
## Deliverable format
```
## Readiness assessment
Source: AEM <version> <on-prem|managed> · Repo <GB> · Assets <n> · Sites <n> · Locales <n>
BPA summary: <critical/major counts by category>
| Finding | Category | Decision (refactor/replace/retire) | Effort (d) | Owner |
## Migration plan
Phases with dates and exit criteria; rehearsal schedule; freeze window with enforcement
Content transfer: migration sets, measured durations, top-up and validation plan
Identity: IMS profiles → AEM groups, Group Migration, UAT roles
Cutover runbook: step · owner · duration · verification · go/no-go
Risk table with mitigations and the rollback position (source read-only until <date>)
```
## Checklist
- [ ] BPA run on production-like content and every finding categorised with an effort figure
- [ ] Manual audit done for admin sessions, file writes, threads and `/etc` literals
- [ ] Project builds green in Cloud Manager before any content moves
- [ ] Indexes converted to lucene and renamed to the Cloud grammar
- [ ] Two rehearsals, the second at production volume, both timed
- [ ] Top-up validation compares counts per tree, including moves and renames
- [ ] IMS product profiles and group mapping done before UAT
- [ ] Processing profiles configured before any asset ingestion
- [ ] Advanced Networking requested early if any integration needs a fixed egress
- [ ] Freeze enforced by permissions, with a change log
- [ ] Cutover runbook has an owner and a verification step per line
- [ ] Forms, Screens and user-generated content scoped separately
## Anti-patterns
- **Moving content before the code builds green** → the target keeps changing under the content you just moved.
- **Treating BPA as the whole assessment** → add the grep audit; BPA does not run your code.
- **Lifting `/etc` designs, static templates and Classic dialogs "to fix later"** → later never comes, and Cloud Service does not support them.
- **Porting custom DAM Update Asset steps** → processing profiles, with genuinely custom work as post-processing or an Asset Compute worker.
- **One untimed transfer on go-live weekend** → two rehearsals, the second at volume.
- **Migrating years of versions and audit logs** → purge first; it is the cheapest hour of the project.
- **A freeze announced by email** → enforce it with permissions and keep a change log.
- **Discovering the Advanced Networking lead time in go-live week** → request it at discovery.
- **Assuming Forms or Screens come along with Sites** → scope them separately.
## Go deeper
- `references/refactor-checklist.md` — the full area-by-area refactor table, the grep list for what BPA cannot see, products that do not migrate, and 6.5 LTS as the alternative.
- `references/content-transfer.md` — CTT step by step, top-up semantics, identity and Group Migration, Bulk Import sources and the CTT comparison, the cutover runbook, freeze enforcement.
- `oak-index-naming.md` in `../../development/aem-backend-development/references/` — the index grammar the Index Converter targets.
- Sibling skills: `aem-cloud-manager` for the pipelines the refactored project ships through, `aem-architecture` for the target design, `aem-dispatcher` for the converted dispatcher config, `aem-assets` for processing profiles.