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

npx skills add AGCO-Global/org-skills --skill aem-cloud-migration
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -g

/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

npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a codex

npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a cursor

npx skills add AGCO-Global/org-skills --skill aem-cloud-migration -a gemini-cli

T-6w  Rehearsal 1: full extraction + ingestion to stage; time it; fix failures
T-3w  Rehearsal 2: repeat with production-size data; validate UAT
T-1w  Code freeze on source; final code on prod
T-2d  Content freeze starts (authors paused or dual-entry list kept)
T-1d  Final top-up extraction + ingestion; publish tree activation; cache warm
T-0   CDN/DNS switch; smoke tests; monitor error rates and 404s
T+2w  Hypercare; source kept read-only as fallback, then decommissioned

## Readiness assessment
Source: AEM <version> <on-prem|managed>  Repo size: <GB>  Assets: <n>  Sites: <n>
BPA summary: <critical/major counts by category>
| Finding | Category | Decision (refactor/replace/retire) | Effort (d) | Owner |

## Migration plan
Phases with dates, exit criteria, rehearsal schedule, freeze window
Content transfer: migration sets, expected durations, top-up plan
Cutover runbook: step, owner, duration, verification, go/no-go
Risk table (as above) and rollback: source stays read-only until <date>
Open questions to verify against current Adobe docs: <list>

---
name: aem-cloud-migration
description: Plan and execute a migration from AEM 6.x (on-prem or managed services) to AEM as a Cloud Service — readiness assessment, code refactoring, content transfer, cutover and risk management. Use this whenever the user mentions moving to AEM Cloud Service or AEMaaCS; runs or reads a Best Practices Analyzer (BPA) report or Cloud Acceleration Manager (CAM); asks about the Content Transfer Tool, extraction/ingestion, top-ups, migration sets, user or IMS mapping, Bulk Import, Repository Modernizer, Index Converter, Dispatcher Converter or AEM Modernization Tools; needs to restructure into ui.apps/ui.content/ui.config, move /etc to /conf, convert OSGi configs to .cfg.json, replace static templates, classic UI or DAM Update Asset workflows; or estimates effort, content freeze and go-live. Also use it for upgrade-vs-migrate decisions, even if they only ask about one BPA finding.
metadata:
  technology: AEM
  type: migration
---

# AEM Cloud Service Migration

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 tools, refactor to cloud rules before moving any content, rehearse transfer on real volumes, and cut over with a frozen, measured top-up. Tool names and capabilities evolve quickly — verify each against current Adobe documentation before committing to a plan.

## 1. Phases

| Phase | Output | Exit criteria |
|---|---|---|
| **Discovery** | BPA report in CAM, inventory (sites, components, integrations, workflows, repo size, users/groups) | Every BPA finding categorised: refactor / replace / retire |
| **Code refactor** | Cloud-compatible project building green in Cloud Manager | 0 critical code quality issues; deploys to dev; features parity-tested |
| **Content transfer rehearsal** | Timed extraction + ingestion to stage (or dev) | Durations known; failures understood; user mapping validated |
| **UAT & performance** | Signed-off stage with migrated content | Business sign-off; load test on stage; SEO/redirect checks |
| **Cutover** | Content freeze → final top-up → DNS/CDN switch | Smoke tests pass; rollback plan (keep source live) ready |
| **Hypercare** | Monitoring, fixes, decommission plan | Stable error rates; source decommissioned on schedule |

## 2. Assessment tools

- **Best Practices Analyzer (BPA)**: install the package on the source (run on a production clone for realistic data), generate the report, upload to **Cloud Acceleration Manager (CAM)**. Findings are grouped by category and importance; CAM tracks readiness and effort.
- **CAM** also hosts migration sets for the Content Transfer Tool and guidance per phase.
- Treat BPA as a floor: it cannot see runtime behaviour (long jobs, file-system writes via libraries, admin sessions hidden behind utilities). Add a manual code audit.

## 3. Code refactoring checklist

| Area | On 6.x | Cloud Service target |
|---|---|---|
| Project structure | One package mixing `/apps` and `/content` | Separate `ui.apps` (immutable), `ui.content` (mutable), `ui.config`, `all` container — **Repository Modernizer** automates much of this |
| `/etc` usage | Designs, cloud configs, tags, workflow models in `/etc` | `/conf` (context-aware configs, templates, workflow models), `/content/cq:tags`, `/apps` for code |
| OSGi configs | `sling:OsgiConfig` nodes, custom runmodes | `.cfg.json` under `config.<runmode>` (`author`, `publish`, `dev`, `stage`, `prod`); env vars/secrets for per-env values |
| Custom indexes | Unversioned Lucene defs, some non-Lucene | Versioned names (`<name>-custom-1`), Lucene-type, deployed in the code package — **Index Converter** helps |
| Templates | Static templates, design dialogs | Editable templates + policies — **AEM Modernization Tools** (page structure, policy import) |
| Components | Foundation / custom copies | Core Components via proxies — Modernization Tools component conversion |
| Dialogs | Classic UI (ExtJS) | Touch UI (Coral 3/Granite) — dialog conversion tool |
| Asset processing | DAM Update Asset workflow + launchers, custom renditions | Asset microservices + **processing profiles**; custom steps as post-processing workflows |
| Replication | Custom agents, reverse replication | Sling Content Distribution (managed); use the `Replicator` API, no custom agents |
| Dispatcher | Any layout | Flexible-mode structure validated by the dispatcher SDK — **Dispatcher Converter** helps |
| Sessions | `loginAdministrative`, admin resolvers | Service users via repoinit + service-user mapping |
| File system | Writes to disk, shared NFS | Repository binaries or external storage; local disk only for temp |
| Background work | Long-running threads, schedulers on every node | Idempotent Sling Jobs; `scheduler.runOn=SINGLE` where appropriate; tolerate pod restarts |
| Networking | Direct outbound IPs, SMTP | Advanced networking (dedicated egress / VPN) where needed |
| Deprecated APIs | Anything flagged by BPA or code quality | Replace; the `aem-sdk-api` compile will fail on removed APIs |

Also check: servlets (prefer resource-type bindings; path-bound servlets bypass resource ACLs and need explicit dispatcher allows), custom login/SSO (move to IMS for authors, SAML for publish users), search (no Solr embedded; use Oak or external), and anything that writes to `/apps` or `/libs` at runtime.

## 4. Content Transfer Tool (CTT)

1. Install CTT on the source author (and publish if needed); ensure disk, Java and version prerequisites.
2. Create a **migration set** in CAM; copy the extraction key to the source.
3. **Extraction** — source → cloud staging storage. Use the pre-copy option for large blob stores where available.
4. **Ingestion** — staging → target environment. Initial ingestion with **wipe**; subsequent **top-ups** without wipe carry deltas since the last extraction.
5. Users/groups referenced by migrated content come along; plan mapping to Adobe IMS identities (Admin Console, bulk user upload or directory sync). Verify the current user-mapping behaviour in docs.
6. Monitor logs in CAM; re-run failed steps; validate counts (pages, assets, tags) against the source.

Rules:
- Migrate **author** content; publish is repopulated by publishing (or ingestion to publish when supported — check docs).
- Purge versions, audit logs and workflow instances on the source first; transfer time scales with repository size.
- Top-ups do not reliably reconcile deletes and moves — keep a freeze for those and re-verify.
- Ingestion with wipe blocks the target environment; schedule it and never wipe prod after go-live.

## 5. Assets at scale

- **Bulk Import** (Assets UI) pulls from cloud blob storage (e.g. Azure Blob, Amazon S3) for large asset libraries, triggering asset microservices processing.
- Plan processing time: every asset gets renditions regenerated; metadata may need a separate CSV import.
- Choose per library: CTT (keeps paths, references, versions) vs Bulk Import (fast, fresh processing, lose history).

## 6. Rehearsal and cutover

```
T-6w  Rehearsal 1: full extraction + ingestion to stage; time it; fix failures
T-3w  Rehearsal 2: repeat with production-size data; validate UAT
T-1w  Code freeze on source; final code on prod
T-2d  Content freeze starts (authors paused or dual-entry list kept)
T-1d  Final top-up extraction + ingestion; publish tree activation; cache warm
T-0   CDN/DNS switch; smoke tests; monitor error rates and 404s
T+2w  Hypercare; source kept read-only as fallback, then decommissioned
```

Redirects, vanity URLs, sitemap and robots, forms endpoints, and integrations' callback URLs are cutover items — list each with an owner.

## 7. Risk table

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Transfer takes longer than freeze window | Medium | High | Rehearse at full size; purge versions; pre-copy blobs |
| Hidden admin sessions / FS writes | High | High | Manual code audit beyond BPA; run on RDE/dev early |
| Custom index mismatch → slow queries | Medium | High | Index Converter + query plan checks on stage |
| Asset reprocessing backlog | Medium | Medium | Stagger ingestion; confirm processing profiles first |
| User/group mapping gaps | Medium | Medium | Map IMS groups before UAT; test with real author roles |
| Integrations blocked by egress | Medium | High | Advanced networking configured before UAT |
| Content drift during freeze | Medium | High | Firm freeze; change log; final top-up validation |

## Deliverable format

```
## Readiness assessment
Source: AEM <version> <on-prem|managed>  Repo size: <GB>  Assets: <n>  Sites: <n>
BPA summary: <critical/major counts by category>
| Finding | Category | Decision (refactor/replace/retire) | Effort (d) | Owner |

## Migration plan
Phases with dates, exit criteria, rehearsal schedule, freeze window
Content transfer: migration sets, expected durations, top-up plan
Cutover runbook: step, owner, duration, verification, go/no-go
Risk table (as above) and rollback: source stays read-only until <date>
Open questions to verify against current Adobe docs: <list>
```

## Anti-patterns to reject

- Moving content before the code builds green in Cloud Manager.
- Treating BPA as complete; skipping a manual audit of sessions, threads and file access.
- Lifting `/etc` designs, static templates and classic dialogs as-is "to fix later".
- Porting custom DAM Update Asset workflow steps instead of using processing profiles.
- Single, untimed content transfer on go-live weekend; no rehearsal at production volume.
- Migrating years of versions, audit logs and workflow history.
- Relying on top-ups to carry deletes and moves.
- Promising specific tool features or limits without checking current documentation.