
aem-cloud-service
All AEM as a Cloud Service skills: component development, Dispatcher config authoring and hardening, workflow design and debugging, code assessment and migration from legacy AEM, content distribution, and Rapid Development Environment (RDE) support.
- version
- 1.4.4
- GitHub stars
- 332
Install
/plugin install aem-cloud-service@adobe-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 8
Beta Skill: This skill is in beta and under active development. Results should be reviewed carefully before use in production. Report issues at https://github.com/adobe/skills/issues
AEM RDE Plugin (aio aem rde) Expert
You help users work with the Adobe I/O CLI plugin for AEM Rapid Development Environments (@adobe/aio-cli-plugin-aem-rde). RDEs are short-lived AEMaaCS environments meant for fast iteration: they accept incremental deployments of bundles, configs, content, dispatcher, frontend, and env-config artifacts without going through Cloud Manager pipelines.
Activation discipline: Only act on this skill when the user has explicitly referenced an RDE concept (RDE, Rapid Development Environment, aio aem rde, @adobe/aio-cli-plugin-aem-rde, RDE snapshots, etc.). Generic AEMaaCS deployment requests ("push my bundle to staging", "tail the publish log", "deploy to dispatcher") belong to Cloud Manager pipelines, not RDE — defer those to other AEMaaCS skills or ask the user to confirm they mean RDE before proceeding.
Your job is to:
- Translate user goals into the right
aio aem rdecommand(s) — including the right deployment type, target (author/publish), and any post-deploy step. - Diagnose RDE problems by combining
status,history <id>,logs, andinspectoutput. - Guide setup/configuration (org/program/env), local vs. global config, experimental feature flags, and CI/build-environment usage.
- Walk users through snapshot create/restore/delete/undelete flows when they need to rebase or back up env state.
Trust the user about what they want; don't run destructive commands (reset, snapshot delete --all, force-deletes) without confirming.
Plugin essentials
- Package:
@adobe/aio-cli-plugin-aem-rde(oclif plugin foraio/ Adobe I/O CLI 10.3+ or 11+) - Install:
aio plugins:install @adobe/aio-cli-plugin-aem-rde - Update:
aio plugins:update - Repo:
https://github.com/adobe/aio-cli-plugin-aem-rde - Topics:
aem:rde— stable commandsaem:rde:inspect— experimental, opt-inaem:rde:snapshot— experimental, opt-in
- Both notations work and are equivalent:
aio aem rde …andaio aem:rde:….
Configuration model — get this right first
Every RDE command needs three IDs from Cloud Manager:
| Config key | Meaning |
|---|---|
cloudmanager_orgid | IMS organization |
cloudmanager_programid | Cloud Manager program |
cloudmanager_environmentid | RDE environment id |
Two ways to set them:
- Interactive (recommended for humans):
aio loginthenaio aem rde setup. Walks the user through org → program → env pickers, optionally stores config locally in a.aiofile in the current working directory. - Scripted / CI (build envs):
aio config:set cloudmanager_orgid <id>etc. Strongly prefer the-l/--localflag so each project pins its own RDE; otherwise the global config bleeds across repos.
aio aem rde setup --show prints the currently active config. aio aem rde setup --enable-notifications / --disable-notifications toggles desktop notifications for long-running tasks.
When working with multiple RDEs, always recommend local config — see references/configuration.md for the storage hierarchy and a concrete multi-env recipe.
Experimental features — opt-in required
inspect and snapshot topics are gated behind a config flag. Until enabled, the commands exist but won't run:
# enable inspect locally for this project
aio config set -l -j aem-rde.experimental-features '["aem:rde:inspect"]'
# enable both inspect and snapshot
aio config set -l -j aem-rde.experimental-features '["aem:rde:inspect","aem:rde:snapshot"]'
Snapshot also requires the customer to be enrolled in the relevant EAP — the API answers 451 NON_EAP otherwise.
Command surface (cheat sheet)
Stable:
| Command | One-liner |
|---|---|
aio aem rde setup | Interactive org/program/env picker |
aio aem rde status | Show env state + deployed artifacts (bundles/configs grouped by author/publish) |
aio aem rde install <location> | Deploy a bundle/config/content/dispatcher/frontend/env-config artifact (URL or path) |
aio aem rde delete <id> | Remove a bundle (BSN[-version]) or OSGi config (PID) |
aio aem rde history [id] | List recent updates; with id, drill into one update's logs |
aio aem rde logs | Tail AEM logs with logger-level filters and highlight |
aio aem rde restart | Restart author + publish |
aio aem rde reset | Reset env to base; long-running, can keep mutable content |
Experimental — aem:rde:inspect:*:
| Command | Purpose |
|---|---|
aio aem rde inspect inventory [id] | List or fetch an inventory (status info) entry |
aio aem rde inspect osgi-bundles [id] | List or fetch a single OSGi bundle |
aio aem rde inspect osgi-components [name] | List or fetch an OSGi component |
aio aem rde inspect osgi-configurations [pid] | List or fetch an OSGi configuration |
aio aem rde inspect osgi-services [id] | List or fetch an OSGi service |
aio aem rde inspect request-logs [id] | List request log entries / drill into one |
aio aem rde inspect request-logs enable | Turn on request logging (per-target) |
aio aem rde inspect request-logs disable | Turn off request logging |
Experimental — aem:rde:snapshot:*:
| Command | Purpose |
|---|---|
aio aem rde snapshot | List snapshots (table sorted by Last Used) |
aio aem rde snapshot create <name> [-d <desc>] | Create a content+deployment snapshot (locks RDE for 2–5 min) |
aio aem rde snapshot restore <name> [--only-mutable-content] | Restore a snapshot; full restore restarts the RDE |
aio aem rde snapshot delete <name> [-f] [--all] | Mark a snapshot for deletion (7-day retention) or wipe it now |
aio aem rde snapshot undelete <name> | Cancel a pending deletion |
Full args/flags for each command live in references/commands.md.
Common cross-cutting flags
-s, --target <author|publish>— restrict to one instance.install/deletedeploy to both by default;inspect/logsdefault toauthor.--organizationId / --programId / --environmentId— one-shot override of stored config (handy for ad-hoc scripts).-q, --quiet— no log output, no prompts. Pair with--jsonfor machine consumption.--json— JSON result (not supported bysetup,logs,inspect:request-logs:enable/disable— they declareenableJsonFlag: false).--no-color— suitable for CI capture.
Deployment types — the install command's hardest decision
aio aem rde install <location> accepts a local path or a public URL. The --type flag picks one of:
osgi-bundle | osgi-config | content-package | content-file | content-xml |
dispatcher-config | frontend | env-config
If --type is omitted, the plugin guesses from the file extension and (for zips on disk) by peeking inside:
| Input | Guessed type |
|---|---|
*.jar | osgi-bundle |
*.json | osgi-config |
zip containing jcr_root/ | content-package |
zip containing conf.dispatcher.d/ | dispatcher-config |
zip with dist/ + package.json | frontend |
zip with any *.yaml entry | env-config |
*.xml with --path | content-xml |
other file with --path | content-file |
For directories, only frontend, dispatcher-config, and env-config work — the plugin builds the zip on the fly. Other types fail with a clear message.
For content-file/content-xml, --path is the JCR repository path. If the source path lives under …/jcr_root/…, the plugin will guess the path; otherwise pass it explicitly.
-r, --restart issues a follow-up restart. Avoid this by default — RDEs accept hot deployment for almost everything; only use it when an OSGi or config change truly needs a full bounce.
-f, --force is for unsticking the env when a previous upload was abandoned. Use sparingly.
When the user describes an artifact, infer the type and target before suggesting a command — see references/deployment-types.md for type-by-type guidance and pitfalls.
Logs command — useful patterns
aio aem rde logs opens a continuous tail until Ctrl-C. It creates an AEM log configuration on the server, polls it every 500 ms, and prints colorized output. Keep these in mind:
- Pass per-level loggers as repeated flags:
-i org.foo -i org.bar -d com.adobe.aem. Levels are-t/--trace,-d/--debug,-i/--info,-w/--warn,-e/--error. - If no logger is provided, the plugin defaults to
-i ""(everything at INFO+). -H "<substring>"highlights matching lines in white (repeatable).-f "<logback-pattern>"overrides the format; default includes timestamp, level, thread, logger, message.--choose— interactive picker over existing log configs (handy when another team member already enabled one).-s/--targetdefaults toauthor; passpublishto tail the publish leg.- AEM allows only a small number of concurrent log configs per env; on
405the plugin offers to remove an existing one.
For triage workflows that combine logs with status/history, see references/workflows.md.
When something fails
The plugin uses these exit codes (handy for CI):
| Code | Meaning |
|---|---|
| 1 | Generic / uncaught error |
| 2 | Configuration error |
| 3 | Validation error in flags or arguments |
| 4 | Deployment error |
| 5 | Internal error — retry may help |
| 40 | Deployment-not-fully-performed (sometimes acceptable mid-pipeline) |
Diagnostic playbook (in order):
aio aem rde setup --show— confirm pointing at the right env.aio aem rde status— is the env evenReady? What's actually deployed?aio aem rde history— see the most recent update; grab the id of the failing one.aio aem rde history <id>— full per-instance log of that update.aio aem rde logs -e "" -w ""— tail errors+warnings for new symptoms.aio aem rde inspect …(if enabled) — read OSGi state to confirm bundles/components/configs are wired correctly.
references/troubleshooting.md has detailed error → likely-cause → fix mappings, including the snapshot-specific error codes (SNAPSHOT_NOT_FOUND, SNAPSHOT_LIMIT, INVALID_STATE, SNAPSHOT_CREATION_STUCK, etc.) and the NON_EAP / DIFFERENT_ENV_TYPE configuration errors.
How to use this skill
When the user asks something:
- "How do I deploy X?" — Identify the artifact, pick the right
--type, decide author/publish, suggestinstall. Point out--restartonly if needed. Referencedeployment-types.mdonly if the type choice is non-obvious. - "My deploy failed." — Walk the diagnostic playbook above. Look for the update id in the user's output and ask for
history <id>if you don't have it. - "I want to switch programs/envs." — Suggest
aio aem rde setup(oraio logout+setupif they're switching IMS orgs). Recommend-lstorage if they juggle multiple RDEs. - "I want a snapshot." — Confirm the customer has the snapshot EAP enabled, then guide create/restore. Always describe expected duration (create ~3–8 min, restore ~7–15 min) so they don't kill the process.
- "Show me what's deployed." —
aio aem rde statusfirst;inspect osgi-bundles/osgi-components/osgi-configurationsfor OSGi-level detail. - "How do I script this in CI?" — Recommend
aio config:set -lfor the three IDs,--quiet --jsonfor commands, and warn againstsetup(it's interactive).
If a question requires deep detail on a single command, read the matching reference file rather than guessing — descriptions, flags, and error codes drift between releases.
Reference files
Read on demand:
references/commands.md— Per-command full args/flags/examples for all stable + experimental commands.references/configuration.md— Config storage hierarchy, multi-RDE patterns, the.aiofile, experimental-feature flags, notifications.references/deployment-types.md— Detailed guidance on each--type, source-path conventions,--pathhandling forcontent-file/content-xml, type guessing rules, gotchas.references/workflows.md— End-to-end recipes: first-time setup, deploy-and-verify, log triage, reset vs. restart vs. snapshot-restore, switching environments, CI usage.references/troubleshooting.md— Error code → meaning → fix; snapshot/non-EAP errors; common deployment failures and recovery.
AEM Cloud Service Workflow
Route user requests to the appropriate specialist skill based on intent.
Intent Router
| User Intent | Skill | Path |
|---|---|---|
| Create a workflow model, add steps, design OR/AND splits, configure variables | Model Design | workflow-model-design/SKILL.md |
| Implement a custom WorkflowProcess step, ParticipantStepChooser, OSGi service registration | Development | workflow-development/SKILL.md |
| Start a workflow from code, HTTP API, Timeline UI, Manage Publication | Triggering | workflow-triggering/SKILL.md |
| Configure a launcher, auto-start on asset upload, overlay OOTB launcher | Launchers | workflow-launchers/SKILL.md |
| Workflow stuck, failed step, missing Inbox task, stale instances, thread pool exhaustion, purge | Debugging | workflow-debugging/SKILL.md |
| Classify a workflow incident, determine required logs, Splunk queries, data gathering checklist | Triaging | workflow-triaging/SKILL.md |
| End-to-end lifecycle or requests spanning multiple concerns | Orchestrator | workflow-orchestrator/SKILL.md |
How to Use
- Match the user's request to one row in the Intent Router table above.
- Read the linked SKILL.md for that specialist skill.
- Follow the workflow, references, and output contract defined in that skill.
- For broad or ambiguous requests that span multiple concerns, use the Orchestrator which coordinates across all specialist skills and loads foundation references.
Cloud Service Constraints
| Constraint | Detail |
|---|---|
| No JMX | No retryFailedWorkItems, countStaleWorkflows, restartStaleWorkflows, purgeCompleted via JMX |
/libs is immutable | Never write to /libs; use /conf/global/ or /apps/ overlays |
| Model design-time path | /conf/global/settings/workflow/models/<id> |
| Model runtime path (for API calls) | /var/workflow/models/<id> |
| Launcher config path | /conf/global/settings/workflow/launcher/config/ |
| Service users | Always use workflow-process-service sub-service; never admin credentials |
| OSGi annotations | DS R6 (@Component, @Reference from org.osgi.service.component.annotations) |
| Deploy via | Cloud Manager pipeline — no Package Manager in production |
Specialist Skills
- workflow-model-design/SKILL.md — model structure, step types, variables, and model XML
- workflow-development/SKILL.md — WorkflowProcess, ParticipantStepChooser, metadata, and error handling
- workflow-triggering/SKILL.md — Timeline UI, Manage Publication, WorkflowSession API, and HTTP API
- workflow-launchers/SKILL.md — launcher configuration, JCR event binding, and OOTB overlay
- workflow-debugging/SKILL.md — stuck workflows, failed steps, thread pools, Sling Jobs, and purge
- workflow-triaging/SKILL.md — symptom classification, log patterns, Splunk queries, and data gathering
- workflow-orchestrator/SKILL.md — full lifecycle orchestration across all skills
AEM as a Cloud Service — Code Assessment
Single skill for detecting and fixing AEM CS code-quality issues, entirely against the local workspace — no external services or network calls. Findings reach the runbook from one of two sources; everything downstream is identical.
Findings sources
| Source | When | Target versions (deps) |
|---|---|---|
| User-named | the user names files or coordinates | user-supplied |
| Discover | the user asks to scan, or names no files | user-supplied (per the pattern's resolution contract) |
Discovery runs through the deterministic analyzer (scripts/analyze.sh):
it parses the workspace once and runs the enabled detectors, emitting the shared findings shape.
Every ready pattern has an analyzer detector. One detector — remove-deprecated-api — loads
its rules dynamically from a preflight-produced cache
(remove-deprecated-api/scripts/detect.sh runs the
AEM Analyser Maven Plugin and writes the cache TSV before the analyzer is invoked); the
detector's shape and integration are otherwise identical. Patterns without a detector are
planned only — not yet detectable and not yet built; there is no LLM-scan fallback in this
version (see Scope & limitations) — the scan value on planned rows in
references/patterns.md marks the intended future detection method,
not an active code path.
Routing
- User named files / coordinates → run the runbook in
with_findingsmode against those paths. - "Scan my repo" / no files named → run the runbook in
discovermode (per-pattern Discovery, workspace roots only).
Then follow the runbook: references/runbook.md.
Manual Pattern Hints (classification → expert skill)
Route the request to one expert skill. Two pattern families share this skill:
Mechanical fixes (analyzer-driven detection, deterministic edits — follow the runbook flow):
| User said / saw | Expert skill |
|---|---|
"update aem sdk", "upgrade mockito", stale <version> or ${property} in pom | outdated-dependencies/ |
"fix @Inject", "modernize Sling Models", javax.inject.Inject on @Model fields | inject-in-sling-model/ |
"add HTTP timeouts", "outbound/external call has no timeout", HttpClient / HttpClients / OkHttpClient built without a timeout | outbound-call-timeouts/ |
"bound my query", "unbounded query", "query causing OOM", p.limit=-1, setLimit(-1) | unbounded-query/ |
| "query is slow", "traversal warning", "is my query indexed", "tune oak index", index coverage of a JCR/Oak query | tuning-oak-query-indexes/ |
| "can the captcha / login / rate limit be skipped", "test-automation bypass", a cookie, header or parameter named test, debug, bypass or skip read in captcha, auth or rate-limit code | request-controlled-security-bypass/ |
"remove deprecated API", "fix deprecated imports", "Cloud Manager deprecated API failure", region-deprecated-api / api-regions-check / Import-Package not satisfied pipeline failures, log4j migration, commons-lang/collections upgrades, deprecated Maven deps, unmodifiable OSGi configs | remove-deprecated-api/ (analyzer detector with dynamic rules — preflight runs aemanalyser-maven-plugin; hint-driven fixes; see recipe.md) |
Architectural migration patterns (guided remediation — full before/after, troubleshooting, modern alternatives; invoked directly or via migration for BPA/CAM-driven discovery):
| User said / saw | Expert skill | BPA pattern ID |
|---|---|---|
org.apache.sling.commons.scheduler.Scheduler or scheduler.schedule( with Runnable | scheduler/ | scheduler |
implements ResourceChangeListener, lightweight listener + JobConsumer | resource-change-listener/ | resourceChangeListener |
com.day.cq.replication.Replicator, org.apache.sling.replication.*, "publish/preview activation" | replication/ | replication |
javax.jcr.observation.EventListener, org.osgi.service.event.EventHandler on non-resource topics (replication, workflow, custom) | event-migration/ | eventListener / eventHandler |
com.day.cq.dam.api.AssetManager create/upload/delete APIs, createAssetForBinary, removeAssetForBinary | asset-manager/ | assetApi |
HTL build warning data-sly-test: redundant constant value comparison | references/data-sly-test-redundant-constant.md | htlLint (reference, no expert skill subdirectory) |
Broad / correctness-review asks ("check my Sling Models are implemented correctly", "review my code", "is my AEM project healthy", "assess this project") are not a single pattern: run the runbook in discover mode with intent report — the analyzer runs every detector and the report covers all built patterns, explicitly noting aspects not yet supported. Only narrow to one pattern when the user targets a specific fix.
If nothing matches, say the issue is not yet supported and offer to file a request for a new expert skill.
Full catalog (built + planned patterns, with severity / detection / fix): references/patterns.md.
Invocation from the migration skill
migration performs BPA/CAM/MCP discovery and handles batching + one-pattern-per-session workflow. After it has identified (pattern, file) pairs from BPA findings, it hands off here for the actual transformation. When invoked with (pattern, file) from migration:
- Skip HA/analyzer discovery (caller already identified the pattern + file)
- Open the pattern's expert skill directly (per the Manual Pattern Hints table above)
- Apply the steps in the expert skill against the named file(s)
- Return the result;
migrationcontinues with the next finding in its batch
The pattern guides themselves are agnostic about who invoked them — they apply identically whether reached from migration (BPA/CAM) or from the runbook in this skill (HA / analyzer).
Runbook
All detection, planning, edits, verification, git/in-place handling, and the run log live in
references/runbook.md. The runbook is the sole owner of repo-environment
detection (edit_mode, git snapshot) — this control plane does not duplicate it.
One pattern per session
Report may span every pattern found; apply touches one pattern per session (atomic revert,
single-story diff). Refuse "fix everything" for the apply phase. Rationale:
references/shared-principles.md.
Critical rules
- Confirm before any write. For apply intent, the request that asked for the fix ("fix it",
"apply") is not the confirmation. Show the Step 7 plan and wait for the user's yes to that plan
before you write anything in the project: source edits, the
autofix/*branch,.autofix/, and a bootstrapAGENTS.md/CLAUDE.md. If you can't ask (a headless or non-interactive run), stop after the plan and say that nothing was changed. Whenmigrationhands off a(pattern, file), its batch flow decides when to edit. - Local only — no network calls or external services; operate solely on the workspace.
Documented exception:
remove-deprecated-apiis plugin-driven and needs Maven Central (to resolveaemanalyser-maven-pluginand, transitively, the AEM SDK's api-regions data) plus optionally Adobe Experience League as a fallback source for successor guidance. If offline, that one pattern is skipped with a clear message; all other patterns remain local-only. - Requires a local JDK (Java 11+) for detection — the analyzer compiles/runs in memory; no install beyond the JDK, no network. If absent, detection stops with a clear message.
- The analyzer is detection — never substitute external tooling. Do not run
mvn versions:display-dependency-updates/mvn versions:display-property-updates,npm outdated, or Maven Central / registry lookups in place of analyzer discovery. Those answer "what is the latest on the network" — outside this skill's local-only contract. If the user explicitly wants a live registry comparison, say it needs network and offer it as a separate step after delivering the skill report.remove-deprecated-api's preflight (remove-deprecated-api/scripts/detect.sh) is the one documented exception: it invokes the AEM Analyser Maven Plugin against the project to populate its rules cache, then hands off to the shared analyzer. - Never commit, push, or open a PR — branch (git) or in-place edits only; the developer reviews and commits.
- Surgical edits — no reformatting / re-serialization.
- No secrets in a report — name a cookie, header or parameter, never the value it is compared
against, nor a token or password from the project: write
<redacted>. This holds in every report, a full scan included. - Skip with a reason — record un-applicable findings as
skippedwith an exact reason; never silently drop. - One pattern per session for apply.
Full rationale: references/shared-principles.md.
Scope & limitations
Local static detection and remediation only — no external services, no network, no live AEM instance. Issues that require runtime or live-repository state, telemetry, or history across runs are out of scope for this skill.
Detection requires a local JDK (Java 11+); there is no remote or LLM-scan fallback in this version.
A large apply (e.g. an @Inject migration across 100+ files) is processed in resumable batches: the run checkpoints each file to .autofix/last-run.json and pauses at a per-pass cap, so it survives context limits — reply apply <pattern> to continue (see references/git-workflow.md).
Adding a new pattern
Full end-to-end procedure — detector → fixtures/tests → catalog + routing → expert skill → verify:
references/adding-a-pattern.md. The [wiring] test keeps the
detector, catalog row, and expert-skill directory in sync.
Triggering scales without touching the description. The description above is intentionally
broad (intent verbs + AEM domain), so it already fires on "check / review / fix my <AEM thing>";
a new pattern is reached by its Manual Pattern Hints + patterns.md rows, not by editing the
description. Update the description only if the new pattern introduces a domain keyword it does
not already cover (a new subsystem or file type). The [wiring] test keeps the detector, catalog
row, and expert-skill directory in sync.
Related skills
migration— drives BPA/CAM/MCP-based legacy-AEM migration workflow. Discovers findings, batches them, enforces one-pattern-per-session, and hands off(pattern, file)pairs to this skill for transformation. See the "Invocation from themigrationskill" section above.
AEM Cloud Service Content Distribution
Beta Skill: This skill is in beta and under active development. Results should be reviewed carefully before use in production. Report issues at https://github.com/adobe/skills/issues
Programmatic content publishing and distribution monitoring using official AEM Cloud Service APIs.
When to Use This Skill
Use this skill collection for:
- Programmatic publishing: Publish content via
ReplicatorAPI - Distribution monitoring: Track distribution lifecycle events
- Automated workflows: Integration with workflow process steps
- Event handling: React to distribution events (failures, completions)
- Custom publishing logic: Bulk operations, Preview tier publishing
Sub-Skills
This is a parent skill that routes to specialized sub-skills based on your task:
| Task | Sub-Skill | File |
|---|---|---|
| Programmatically publish/unpublish content | Replication API | replication/SKILL.md |
| Monitor distribution events and lifecycle | Sling Distribution Events | sling-distribution/SKILL.md |
Quick Decision Guide
Choose Replication API when you need to:
- Publish content from custom OSGi services
- Integrate publishing into workflow steps
- Perform bulk publishing operations
- Publish to Preview tier for review
- Check replication status programmatically
Choose Sling Distribution Events when you need to:
- Monitor distribution lifecycle (created, queued, distributed, imported)
- React to distribution failures
- Trigger post-distribution actions (cache warming, notifications)
- Audit distribution operations
- Track distribution metrics
Official APIs
Both skills use official, supported AEM Cloud Service APIs:
-
Replication API:
com.day.cq.replication- Javadoc: https://developer.adobe.com/experience-manager/reference-materials/cloud-service/javadoc/com/day/cq/replication/package-summary.html
- Main Classes:
Replicator,ReplicationOptions,ReplicationStatus,ReplicationActionType
-
Sling Distribution API:
org.apache.sling.distribution- Javadoc: https://developer.adobe.com/experience-manager/reference-materials/cloud-service/javadoc/org/apache/sling/distribution/package-summary.html
- Main Packages:
org.apache.sling.distribution.event(event topics and properties)
Architecture Overview
┌──────────────────────────────────────────────────┐
│ Replication API (Your Code) │
│ com.day.cq.replication.Replicator │
│ │
│ replicator.replicate(session, ACTIVATE, path) │
└────────────────────┬─────────────────────────────┘
↓
┌──────────────────────────────────────────────────┐
│ Sling Distribution (Underlying Transport) │
│ org.apache.sling.distribution │
│ │
│ [AGENT_PACKAGE_CREATED] ← Distribution events │
│ ↓ fire at each stage │
│ [AGENT_PACKAGE_QUEUED] │
│ ↓ │
│ [AGENT_PACKAGE_DISTRIBUTED] │
│ ↓ │
│ Adobe Developer Pipeline Service │
│ ↓ │
│ [IMPORTER_PACKAGE_IMPORTED] │
└──────────────────────────────────────────────────┘
↓
Content live on Publish/Preview
How It Works
- Your code calls
Replicator.replicate()to publish content - Sling Distribution packages content and fires
AGENT_PACKAGE_CREATEDevent - Package is queued and
AGENT_PACKAGE_QUEUEDevent fires - Package is sent to Adobe Developer pipeline and
AGENT_PACKAGE_DISTRIBUTEDevent fires - Target tier imports content and
IMPORTER_PACKAGE_IMPORTEDevent fires - Content is live on target tier (Publish or Preview)
Common Patterns
Pattern 1: Publish and Monitor
Publish content and track when it goes live:
// Step 1: Publish using Replication API
@Reference
private Replicator replicator;
public void publishContent(Session session, String path) throws ReplicationException {
replicator.replicate(session, ReplicationActionType.ACTIVATE, path);
}
// Step 2: Monitor completion using Distribution Events
@Component(service = EventHandler.class, property = {
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED
})
public class PublishCompletionHandler implements EventHandler {
@Override
public void handleEvent(Event event) {
String[] paths = (String[]) event.getProperty(
DistributionEventProperties.DISTRIBUTION_PATHS
);
LOG.info("Content is now live: {}", String.join(",", paths));
// Trigger post-publish actions (cache warming, notifications, etc.)
}
}
Pattern 2: Preview-First Workflow
Publish to Preview for approval, then to Publish:
// Workflow Step 1: Publish to Preview
public void publishToPreview(Session session, String path) throws ReplicationException {
ReplicationOptions options = new ReplicationOptions();
options.setFilter(agent -> "preview".equals(agent.getId()));
replicator.replicate(session, ReplicationActionType.ACTIVATE, path, options);
}
// Workflow Step 2: After approval, publish to Publish tier
public void publishToProduction(Session session, String path) throws ReplicationException {
ReplicationOptions options = new ReplicationOptions();
options.setFilter(agent -> "publish".equals(agent.getId()));
replicator.replicate(session, ReplicationActionType.ACTIVATE, path, options);
}
Pattern 3: Auto-Publish with Failure Handling
Auto-publish content and alert on failures:
// Publish handler
@Component(service = EventHandler.class, property = {
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
SlingConstants.TOPIC_RESOURCE_CHANGED
})
public class AutoPublishHandler implements EventHandler {
@Reference
private Replicator replicator;
@Override
public void handleEvent(Event event) {
String path = (String) event.getProperty(SlingConstants.PROPERTY_PATH);
if (shouldAutoPublish(path)) {
try (ResourceResolver resolver = getServiceResolver()) {
Session session = resolver.adaptTo(Session.class);
replicator.replicate(session, ReplicationActionType.ACTIVATE, path);
} catch (Exception e) {
LOG.error("Auto-publish failed", e);
}
}
}
}
// Failure monitoring
@Component(service = EventHandler.class, property = {
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
DistributionEventTopics.AGENT_PACKAGE_DROPPED
})
public class FailureAlertHandler implements EventHandler {
@Reference
private AlertService alertService;
@Override
public void handleEvent(Event event) {
String packageId = (String) event.getProperty(
DistributionEventProperties.DISTRIBUTION_PACKAGE_ID
);
alertService.sendAlert("Distribution failed", packageId);
}
}
Rate Limits and Constraints
| Constraint | Limit | Impact |
|---|---|---|
| Paths per API call (recommended) | 100 | Transactional guarantee; system auto-splits above this |
| Payload size | 10 MB | Excluding binaries |
Note:
ReplicationOptions.setUseAtomicCalls()is@Deprecated/ "no longer required" per the Cloud Service Javadoc — the system handles auto-bucketing automatically for >100 paths.
Best Practice: For large hierarchical content trees, use the Tree Activation workflow step instead of custom code.
Key Differences from AEM 6.x
| Feature | AEM 6.x | AEM Cloud Service |
|---|---|---|
| Replication API | com.day.cq.replication.Replicator | ✅ Same API |
| Replication agents | Manual configuration | ✅ Automatic (managed by Adobe) |
| Transport mechanism | Direct JCR replication | ✅ Sling Distribution via Adobe pipeline |
| Preview tier | Not available | ✅ Available (requires agent filtering) |
| Distribution events | Limited | ✅ Full lifecycle via org.apache.sling.distribution.event |
| Agent configuration | Manual OSGi config | ❌ Not exposed (managed by Adobe) |
When NOT to Use These Skills
Use UI workflows instead when:
- Publishing small amounts of content manually
- One-off publishing operations
- Content authors can use Quick Publish or Manage Publication
Use Tree Activation workflow when:
- Publishing large hierarchical content trees
- Bulk operations across hundreds of paths and no custom logic is needed
Quick Reference
Replication API Basics
// Inject service
@Reference
private Replicator replicator;
// Publish single page
replicator.replicate(session, ReplicationActionType.ACTIVATE, "/content/mysite/page");
// Unpublish
replicator.replicate(session, ReplicationActionType.DEACTIVATE, "/content/mysite/page");
// Bulk publish (≤100 for transactional guarantee)
replicator.replicate(session, ReplicationActionType.ACTIVATE,
new String[]{"/content/page1", "/content/page2"}, null);
// Publish to Preview
ReplicationOptions options = new ReplicationOptions();
options.setFilter(agent -> "preview".equals(agent.getId()));
replicator.replicate(session, ReplicationActionType.ACTIVATE, "/content/page", options);
// Check status
ReplicationStatus status = replicator.getReplicationStatus(session, "/content/page");
boolean isPublished = status != null && status.isActivated();
Distribution Event Handling Basics
// Listen for distribution events
@Component(service = EventHandler.class, property = {
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
DistributionEventTopics.AGENT_PACKAGE_CREATED,
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
DistributionEventTopics.AGENT_PACKAGE_DISTRIBUTED,
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
DistributionEventTopics.AGENT_PACKAGE_DROPPED,
org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +
DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED
})
public class DistributionMonitor implements EventHandler {
@Override
public void handleEvent(Event event) {
String topic = event.getTopic();
String packageId = (String) event.getProperty(
DistributionEventProperties.DISTRIBUTION_PACKAGE_ID
);
String[] paths = (String[]) event.getProperty(
DistributionEventProperties.DISTRIBUTION_PATHS
);
// Handle event based on topic
if (DistributionEventTopics.AGENT_PACKAGE_DROPPED.equals(topic)) {
LOG.error("Distribution failed: {}", packageId);
} else if (DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED.equals(topic)) {
LOG.info("Content is live: {}", String.join(",", paths));
}
}
}
Best Practices
- Use the right API: Replication API for publishing, Distribution events for monitoring
- Respect rate limits: ≤100 paths for transactional guarantee
- Handle failures: Always catch
ReplicationException, monitorAGENT_PACKAGE_DROPPEDevents - Use service users: Never use admin credentials
- Filter events appropriately: Only listen to events you need
- Validate permissions: Call
replicator.checkPermission()before replication - Publish only what's needed: Avoid unnecessary bulk operations
Troubleshooting
Replication Issues
| Issue | Solution |
|---|---|
ReplicationException | Check service user has crx:replicate permission |
| Content not on target tier | Verify agent filter, check replication status |
| "Too many paths" error | Use ≤100 paths for transactional guarantee, or pass all paths — system auto-splits |
Event Handling Issues
| Issue | Solution |
|---|---|
| Event handler not firing | Verify event topic constant matches exactly |
| Missing event properties | Always null-check event properties |
| Handler slowing distribution | Use async job processing, don't block |
Detailed Documentation
For detailed examples, code samples, and advanced usage:
- Replication API: See replication/SKILL.md
- Sling Distribution Events: See sling-distribution/SKILL.md
References
- Replication Javadoc: https://developer.adobe.com/experience-manager/reference-materials/cloud-service/javadoc/com/day/cq/replication/package-summary.html
- Sling Distribution Javadoc: https://developer.adobe.com/experience-manager/reference-materials/cloud-service/javadoc/org/apache/sling/distribution/package-summary.html
- Adobe Documentation: https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/operations/replication.html
- Sling Distribution: https://sling.apache.org/documentation/bundles/content-distribution.html
- Service Users / Repo Init: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/aem-project-content-package-structure#repo-init
AEM Component Creation Skill
Creates complete AEM components following Adobe best practices.
Configuration Gate Check — Do This First
This configuration check needs to happen first because without it, the skill will use incorrect project paths and package names, causing every generated file to be wrong.
First tool call: Read .aem-skills-config.yaml in the project root (same level as pom.xml).
Check: Does the file exist and does it have configured: true?
| Status | Action |
|---|---|
| File missing or configured: false | Stop and display the error message below. Do not explore the codebase or proceed — the config values are needed for correct file paths and naming. Wait for the user to configure. |
| configured: true | Read project, package, and group values from the YAML file. Proceed with component creation. |
If NOT configured, Display This Message and Stop:
Project configuration required!
Before creating components, configure your project settings in:
`.aem-skills-config.yaml` (in your project root, same level as pom.xml)
Open the file and update:
- project: Your AEM project name (e.g., 'mysite', 'wknd')
- package: Your Java package (e.g., 'com.mysite.core')
- group: Your component group (e.g., 'MySite Components')
- configured: true
After updating, ask me to create the component again.
Why you should not explore the codebase when unconfigured:
Doing any of the following before configuration is set will lead to incorrect assumptions and wasted effort:
- Reading any other repository files
- Listing directories to "understand the project"
- Checking existing components for patterns
- Looking at pom.xml, Java files, or folder structures
- Inferring values from any source
The config file is the single source of truth for project values — skipping it leads to wrong paths and package names in every generated file.
No Hallucination Rule
Only create the exact fields the user specified — adding extra fields creates authoring confusion and maintenance burden, and renaming fields breaks content contracts.
Load reference for full rules: references/no-hallucination-rules.md
Workflow Overview
| Step | Action |
|---|---|
| 0 | Configuration validation (do this first — see above) |
| 1 | Extract & validate component name |
| 1.5 | Component extension decision (if extending) |
| 2 | Gather requirements & confirm dialog specification |
| 2.3 | Figma design fetch (if Figma URL provided) |
| 3 | Create all component files |
| 3.11 | Dependency verification (required for servlets) |
| 4 | Completion summary |
Step 0: Configuration Validation
0.1 Read Configuration
- Read
.aem-skills-config.yamlfrom the project root - Check that
configured: true - Read
project,package, andgroupvalues
0.2 Validate — Use Only the Config File
Do not infer project values from the file system, existing components, Java files, pom.xml, or prior knowledge. These sources may be outdated or inconsistent — .aem-skills-config.yaml is the single source of truth because the user explicitly sets it.
0.3 Load Conventions
- Read
references/aem-conventions.mdfor file structure templates, naming conventions, and patterns
0.4 Project State Analysis (after configuration validated)
- Check Component Name Uniqueness - Look in
/apps/[project]/components/ - Check Model Class Conflicts - Look in
core/src/main/java/[package-path]/models/ - Analyze Existing Patterns - Review 1-2 recent components for style reference
Step 1: Extract & Validate Component Name
- Parse component name from user's message (ask if not provided)
- Normalize to lowercase kebab-case (e.g.,
My Component->my-component) - Validate: starts with letter, only letters/numbers/hyphens, no consecutive hyphens
Step 1.5: Component Extension Decision
When user says "extend {component}":
Tier 1: Check Project Components First
- Search
/apps/{project}/components/{component} - If found -> Use as
sling:resourceSuperType
Tier 2: Check Core Components
| User Says | Maps To |
|---|---|
| image | core/wcm/components/image/v3/image |
| teaser, card | core/wcm/components/teaser/v2/teaser |
| text, richtext | core/wcm/components/text/v2/text |
| title, heading | core/wcm/components/title/v3/title |
| list | core/wcm/components/list/v4/list |
| button, cta | core/wcm/components/button/v2/button |
| navigation, nav | core/wcm/components/navigation/v2/navigation |
| container, section | core/wcm/components/container/v1/container |
| accordion | core/wcm/components/accordion/v1/accordion |
| tabs | core/wcm/components/tabs/v1/tabs |
| carousel | core/wcm/components/carousel/v1/carousel |
| embed, video | core/wcm/components/embed/v2/embed |
Tier 3: Not Found - Ask user for clarification.
For extension patterns, load: references/extending-core-components.md
Step 1.6: Core Component Extension Requirements
Required when extending with "hide", "remove", "add custom field", or "override" (these operations need Sling Resource Merger patterns to work correctly):
Load reference: references/extending-core-components.md
| User Request | Action |
|---|---|
| "Add custom fields" | Create new tab OR add to existing |
| "Hide {tab}" | Use sling:hideResource="{Boolean}true" |
| "Hide {field}" | Use sling:hideResource="{Boolean}true" |
| "Override {field}" | Use sling:hideProperties + new values |
When extending Core Components:
- Use
@Self @Via(type = ResourceSuperType.class)for model delegation - Implement
ComponentExporterinterface - Add
resourceTypeto@Modelannotation - Use
sling:hideResourcein dialog for inherited tabs/fields
Note: If the parent component is a project component (not a Core Component), use direct Java class extension (
extends ParentModel) instead of the delegation pattern. The@Self @Via(type = ResourceSuperType.class)pattern is only for Core Components. Loadreferences/extending-core-components.mdfor the decision table.
Step 2: Gather Requirements
2.1 Parse Dialog Specification
Echo back EXACTLY what you understood before creating:
Dialog Specification Confirmed:
I will create exactly {N} fields:
| # | Field Label | Field Type | Property Name |
|---|-------------|------------|---------------|
| 1 | {label1} | {type1} | {name1} |
No additional fields will be added.
Is this correct?
2.2 Mockup Image Handling
- Both mockup AND spec provided: Dialog spec takes precedence. Mockup for HTML/CSS only.
- Only mockup provided: Propose fields and ASK for confirmation.
2.3 Figma Design Input
Load: references/figma-design-rules.md
When user provides a Figma URL (figma.com/design/..., figma.com/make/..., or figma.com/board/...):
- Parse the URL to extract
fileKeyandnodeId(see references/figma-design-rules.md Rule 1)
- Convert
-to:in thenode-idquery parameter - Use
branchKeyasfileKeyfor branch URLs
- **Call **
get_design_contextvia theplugin-figma-figmaMCP server (see Rule 2):{ "server": "plugin-figma-figma", "toolName": "get_design_context", "arguments": { "nodeId": "<extracted-node-id>", "fileKey": "<extracted-file-key>", "clientLanguages": "html,css,javascript", "clientFrameworks": "htl" } } - Extract design tokens from the response — colors, fonts, sizes, spacing, layout (see Rules 3-4)
- Use the Figma output for HTL structure, CSS styling, and JS behavior — NOT for dialog fields
Precedence when BOTH dialog spec AND Figma URL are provided:
- Dialog specification → determines dialog fields (absolute precedence, no hallucination)
- Figma design → determines HTML structure, CSS styling, JS behavior only
When ONLY Figma URL is provided (no dialog spec):
- Analyze the design and PROPOSE dialog fields to the user
- ASK for confirmation before proceeding
Figma response handling:
- The response is React+Tailwind — treat as a REFERENCE, not production code
- Convert JSX to semantic HTL with BEM classes (see Rule 5)
- Extract all CSS values to the component clientlib (see Rule 6)
- Create JS only if interactivity is implied (see Rule 7)
- Do not hardcode Figma temporary image URLs — they expire and will break in production (see Rule 8)
2.4 Dynamic Content Requirements
| User Indicates | Servlet Required? |
|---|---|
| External API integration | Yes (GET) |
| Dynamic data loading | Yes (GET) |
| Form submission | Yes (POST) |
| Search/filter | Yes (GET) |
| Static dialog content | No |
Step 3: Create Component Files
Create ALL files in this order:
3.1 Component Definition
Path: ui.apps/src/main/content/jcr_root/apps/[project]/components/{component-name}/.content.xml
Load: references/aem-conventions.md
3.2 Component Dialog
Path: ui.apps/.../components/{component-name}/_cq_dialog/.content.xml
Load: references/dialog-patterns.md
For extended components: Load references/extending-core-components.md — Sling Resource Merger is required here because dialog inheritance only works through the merger; without it, parent dialog nodes won't be resolved.
3.2.1 Image Field Handling
When a user specifies an image or photo field:
- Default approach: Embed the Core Image component via
data-sly-resource— do NOT create a fileupload dialog field with manual<img>rendering. - Fileupload is only for non-image files (PDFs, documents, etc.). Only use
cq/gui/components/authoring/dialog/fileuploadwhen the user explicitly asks for a non-image file upload. - Load
references/htl-patterns.md(Image Handling section) for the correct embedding pattern.
3.3 HTL Template
Path: ui.apps/.../components/{component-name}/{component-name}.html
Load: references/htl-patterns.mdIf Figma URL provided, ALSO load: references/figma-design-rules.md (Rules 5, 8) — Convert JSX structure to semantic HTL with BEM classes. Replace static text with Sling Model expressions. Use the Figma screenshot as visual truth for element hierarchy.
i18n check: If the component has static display text (labels, button text, placeholder strings), use HTL i18n expressions: ${'Label Text' @ i18n}. Do not handle static text translation in the Sling Model — keep it in HTL where translation is automatic.
3.4 Sling Model
Path: core/src/main/java/[package-path]/models/{ComponentName}Model.java
Load: references/model-patterns.md, references/java-standards.md
For extensions: Load references/extending-core-components.md
Delegation Pattern (for Core Component extensions):
@Model(adaptables = SlingHttpServletRequest.class,
adapters = {CustomModel.class, ComponentExporter.class},
resourceType = CustomModel.RESOURCE_TYPE)
@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME,
extensions = ExporterConstants.SLING_MODEL_EXTENSION)
public class CustomModel implements ComponentExporter {
@Self @Via(type = ResourceSuperType.class)
private com.adobe.cq.wcm.core.components.models.List coreList;
// Use FQN for core interfaces to avoid import collision
}
3.5 Child Item Model - If Multifield
Path: core/src/main/java/[package-path]/models/{ItemName}.java
3.6 Unit Test
Path: core/src/test/java/[package-path]/models/{ComponentName}ModelTest.java
Load: references/test-patterns.md
3.7 Component Clientlib — Create for Every Component
Path: ui.apps/.../clientlibs/clientlib-{component-name}/
Load: references/clientlib-patterns.mdIf Figma URL provided, ALSO load: references/figma-design-rules.md (Rules 6, 7) — Extract exact colors, fonts, sizes, spacing, border-radius from the Figma response. Place all CSS into css/{component-name}.css using BEM naming. Create JS in js/{component-name}.js only if the design implies interactivity. Verify pixel-perfect fidelity against the Figma screenshot.
3.8 Dialog Clientlib - If Conditional Logic
Path: ui.apps/.../clientlibs/clientlib-{component-name}-dialog/
Load: references/clientlib-patterns.md (Dialog JavaScript Pattern section)
3.9 Sling Servlet - If Dynamic Content
Path: core/src/main/java/[package-path]/servlets/{ComponentName}Servlet.java
Load: references/sling-servlet-standards.md
3.10 Servlet Unit Test
Path: core/src/test/java/[package-path]/servlets/{ComponentName}ServletTest.java
3.11 Dependency Verification — Required for Servlets
Before completing, verify dependencies in core/pom.xml:
- Do not hardcode versions — check parent pom.xml for version properties instead, since hardcoded versions drift out of sync and cause build conflicts
- Most common APIs included in
aem-sdk-api(GSON, Jackson, Commons) - Use
providedscope for AEM runtime libraries
Step 4: Completion Summary
Component '{component-name}' created successfully!
## Files Created
- ui.apps/.../components/{component-name}/.content.xml
- ui.apps/.../components/{component-name}/_cq_dialog/.content.xml
- ui.apps/.../components/{component-name}/{component-name}.html
- core/.../models/{ComponentName}Model.java
- core/.../models/{ComponentName}ModelTest.java
- ui.apps/.../clientlibs/clientlib-{component-name}/
[+ servlet files if applicable]
## Dialog Fields (Exact Match)
{table matching specification}
Would you like me to add any additional fields or build the project?
Quick Reference: Field Type Mapping
| User Says | Granite Resource Type |
|---|---|
| Textfield | granite/ui/components/coral/foundation/form/textfield |
| Textarea | granite/ui/components/coral/foundation/form/textarea |
| Richtext, RTE | cq/gui/components/authoring/dialog/richtext |
| Pathfield, Path | granite/ui/components/coral/foundation/form/pathfield |
| Image, Photo | Embed Core Image component (see references/htl-patterns.md Image Handling section). Do not use fileupload for image rendering. |
| Fileupload, File Upload | cq/gui/components/authoring/dialog/fileupload (for non-image files: PDFs, documents) |
| Multifield | granite/ui/components/coral/foundation/form/multifield |
| Checkbox | granite/ui/components/coral/foundation/form/checkbox |
| Select, Dropdown | granite/ui/components/coral/foundation/form/select |
| Numberfield | granite/ui/components/coral/foundation/form/numberfield |
| Datepicker | granite/ui/components/coral/foundation/form/datepicker |
For complete mappings: assets/field-type-mappings.md
Reference Files
Load on-demand based on what you're creating:
| Creating | Load Reference |
|---|---|
| Any component | .aem-skills-config.yaml (project root, load first — see Configuration Gate Check), then references/aem-conventions.md |
| Dialog XML | references/dialog-patterns.md |
| HTL Template | references/htl-patterns.md |
| Sling Model | references/model-patterns.md, references/java-standards.md |
| Unit Tests | references/test-patterns.md |
| Clientlibs | references/clientlib-patterns.md |
| Extending Core Component | references/extending-core-components.md |
| Extending Core Component — worked example & checklists | references/extending-core-components-example.md (load when you need a complete worked example of extending a Core Component, unit testing patterns, or the implementation checklist) |
| Sling Servlet | references/sling-servlet-standards.md |
| Core Component patterns | references/core-components.md |
| No Hallucination rules | references/no-hallucination-rules.md |
| Figma design integration | references/figma-design-rules.md |
| Troubleshooting | references/troubleshooting.md |
| Examples | references/examples.md |
If encountering issues during or after component creation, consult references/troubleshooting.md for common problems and solutions.
AEM Cloud Service Dispatcher
Route user requests to the appropriate specialist skill based on intent.
Intent Router
| User Intent | Skill | Path |
|---|---|---|
Create, modify, review, or harden dispatcher config files (.any, vhost, rewrite, cache, filter) | Config Authoring | config-authoring/SKILL.md |
Conceptual questions (statfileslevel, filter rules, URL decomposition, cache invalidation, rewrite behavior, security headers) | Technical Advisory | technical-advisory/SKILL.md |
| Investigate runtime incidents, failures, probe regressions, or cache anomalies | Incident Response | incident-response/SKILL.md |
| Optimize cache efficiency, latency, and throughput | Performance Tuning | performance-tuning/SKILL.md |
| Security audit, threat model, exposure control, header hardening | Security Hardening | security-hardening/SKILL.md |
| End-to-end lifecycle (design → implement → validate → release → incident) or requests spanning multiple concerns | Workflow Orchestrator | workflow-orchestrator/SKILL.md |
How to Use
- Match the user's request to one row in the Intent Router table above.
- Read the linked SKILL.md for that specialist skill.
- Follow the workflow, references, and output contract defined in that skill.
- For broad or ambiguous requests that span multiple concerns, use the Workflow Orchestrator which coordinates across all specialist skills.
MCP Tool Contract
All specialist skills share the same core-7 MCP tool set:
validate— static config validationlint— deep/order-aware lintingsdk— SDK check-files and diff-baselinetrace_request— trace a request through dispatcherinspect_cache— inspect cache statemonitor_metrics— runtime metricstail_logs— log tailing
Specialist Skills
- config-authoring/SKILL.md — config file design, edits, and validation
- technical-advisory/SKILL.md — policy, documentation, cloud guardrails, and evidence planning
- incident-response/SKILL.md — runtime incident triage and remediation
- performance-tuning/SKILL.md — cache and throughput optimization
- security-hardening/SKILL.md — security audit and hardening
- workflow-orchestrator/SKILL.md — full lifecycle orchestration across all skills
Ensure AGENTS.md and CLAUDE.md (bootstrap)
Mandatory order (all cases)
Before any other work — including dispatcher, create-component, code edits, MCP, or answers — the agent MUST:
- Check whether
AGENTS.mdexists at the workspace (repository) root. - If it exists → skip this skill entirely and continue with the user’s request.
- If it does not exist and the repo is an AEM Cloud Service project (see Gate check), and When to hold off does not apply → run this skill completely first (create
AGENTS.mdandCLAUDE.mdif missing), then fulfill the user’s original request.
This applies to every user message and any intent (bugs, features, questions, dispatcher, etc.) until AGENTS.md is present. Do not defer bootstrap to “after” the main task.
It creates AGENTS.md and CLAUDE.md at the repository root so every AI coding agent (Claude Code, Cursor, etc.) gets project guidance, optionally tailored using the module catalog and add-on detection.
When to hold off
Creating the two files changes the user's project. Don't create them yet when:
- the user asked for a review, scan, audit or report, or said not to change anything; or
- the request is a fix of AEM Java, OSGi or Maven code, which
code-assessmentplans and asks about first, and the user has not said yes to that plan yet.
Then do the user's request without them, and offer the files in your answer or add them to the plan. Create them only after the user agrees. If the run can't ask the user (headless, non-interactive), don't create them.
Gate check
- Look for
AGENTS.mdat the workspace root. If it exists → skip, move on. - Verify this is an AEM Cloud Service project: root
pom.xmlexists and referencescom.adobe.aem:aem-sdk-apioraem-project-archetypeor contains<modules>with typical AEM module names (core,ui.apps,dispatcher, etc.). If not an AEM project → skip.
Steps
1. Resolve project name
Check in order:
- Root
pom.xml→<name>element (preferred, usually human-readable). - Root
pom.xml→<artifactId>, then humanize: strip leadingaem-, replace-with spaces, title-case (e.g.aem-guides-wknd→WKND,my-site→My Site). - Directory name of the workspace.
- Fallback:
"AEM Cloud Service Project".
2. Discover modules
Read root pom.xml <modules> section. For each <module>, confirm the directory actually exists.
Build a list of present modules.
3. Detect add-ons and frontend type
Scan the project for:
| Signal | Add-on / variant |
|---|---|
pom.xml depends on cif-connector or aem-core-cif-components | CIF (Commerce) |
ui.frontend/package.json contains react or @adobe/aem-react-editable-components | React SPA |
ui.frontend/package.json contains @angular/core or @adobe/aem-angular-editable-components | Angular SPA |
ui.frontend has no clientlib.config.js and pom.xml references frontend-maven-plugin but outputs no clientlibs | Decoupled frontend |
pom.xml depends on aem-forms-* or forms.core | AEM Forms |
Module ui.frontend.react.forms.af exists | Headless Forms |
pom.xml uses precompiled-scripts-provider | Precompiled Scripts |
If none of these are detected, treat as General Webpack frontend (the default archetype).
4. Generate AGENTS.md
Read the template at references/AGENTS.md.template. Apply the following adaptations:
a. Title
Replace {{PROJECT_NAME}} with the resolved project name.
b. Add-ons section
If any add-ons were detected (CIF, Forms, Headless Forms, Precompiled Scripts), insert an "Add-ons and extensions" section after the intro paragraph. Use descriptions from the references/module-catalog.md add-ons table. If none detected, omit the section entirely.
c. Modules section
Only include modules that actually exist in the project. For each module, use the matching description from the module catalog. Pay attention to:
ui.frontend— use the variant that matches the detected frontend type (General, React, Angular, Decoupled).dispatcher— only include if thedispatcherdirectory exists.it.tests/ui.tests— only include if they exist.
d. Build commands
- Include frontend commands (
npm run build,npm start) only ifui.frontendexists. - Include dispatcher validate command only if
dispatchermodule exists. - For React/Angular SPA, note that
npm startrequires AEM running.
e. Important resources
Always include the base resources from the template. Additionally:
- If React or Angular SPA detected → add SPA Editor and framework-specific resources (see module catalog).
- If CIF detected → add Commerce resources.
- If Forms detected → add Forms resources.
- If Decoupled frontend → add Frontend Pipeline resource.
5. Create CLAUDE.md
If CLAUDE.md does not exist at the workspace root, create it with exactly this content (so Claude/Cursor picks up project guidance):
@AGENTS.md
Do not overwrite an existing CLAUDE.md.
6. Inform the user
Briefly tell the user:
"I created
AGENTS.mdandCLAUDE.mdin your project root with guidance tailored to your project structure. These help AI coding agents understand your project."
Then continue with the user's original request.
Reference files
| File | Purpose |
|---|---|
| references/AGENTS.md.template | Base template with {{PROJECT_NAME}} placeholder and all default sections |
| references/module-catalog.md | Module descriptions, add-on descriptions, conditional resources — the source of truth for adapting the template |
Rules
- Never overwrite an existing
AGENTS.mdorCLAUDE.md. Only create when missing. - Never hallucinate modules. Only list modules whose directories actually exist.
- Keep the generated AGENTS.md clean — no skill metadata, no comments about "generated by skill".
- Project name should be human-readable (e.g. "WKND Sites Project", "My Site"), not only a raw artifactId unless that is the desired title.
- Do not add sections that tell agents to use specific MCP servers, Cursor/Claude skills, or how to discover tools. Coding assistants pick those up from product configuration and tool metadata; if something is not discovered, fix metadata or MCP setup — do not duplicate that in AGENTS.md.
- The resource links must point to
experienceleague.adobe.com/en/docs/experience-manager-cloud-service/...(Cloud Service URLs), never to AEM 6.5 URLs.
AEM as a Cloud Service — Code Migration
Source → target: Legacy AEM 6.x / AMS / on-prem → AEM as a Cloud Service. Scoped under skills/aem/cloud-service/skills/migration/ so this is not confused with Edge Delivery or 6.5 LTS.
This skill drives the migration workflow: BPA data, CAM/MCP, one pattern per session, and target discovery. Transformation rules and steps live in the code-assessment skill — once a finding's pattern is identified, hand off to {code-assessment}/<pattern>/SKILL.md (or the relevant shared reference under {code-assessment}/references/).
Setup: Use the aem-cloud-service install (see repository root README) so both migration and code-assessment paths are available. If you already have the monorepo open with resolvable {code-assessment} paths, no separate install step is required.
For the person driving the agent: references/quick-start.md has what to say for each kind of migration, with copy-paste prompts.
Path convention (Adobe Skills monorepo)
From the repository root (parent of the skills/ directory):
| Symbol | Path |
|---|---|
{code-assessment} | skills/aem/cloud-service/skills/code-assessment/ |
Examples: {code-assessment}/SKILL.md, {code-assessment}/scheduler/SKILL.md, {code-assessment}/references/scr-to-osgi-ds.md.
Workspace scope (IDE) — user code only
Applies to finding and editing the user's AEM project (Java, bundles, config, HTL), not to reading installed skill files under {code-assessment}.
- Treat the current IDE workspace root folder(s) (single- or multi-root) as the only boundary for searches, globs,
grep, and file reads/writes for migration targets. - Do not search parent directories, sibling folders on disk,
~, other clones, or arbitrary absolute paths to "discover" sources unless the user explicitly names those paths or asks you to include them. - BPA CSV / CAM targets: If a
filePathor class-to-file mapping does not resolve under a workspace root, stop and tell the user which paths are missing — do not hunt elsewhere on the filesystem. Ask them to open the correct project in the IDE or adjust paths. - Manual flow: Only migrate files the user named that live under the workspace (or paths they explicitly provided). Do not expand scope by searching outside the workspace.
Required delegation (do this first)
Find the branch for the request and read its file before anything else. Each of Branches A and C–I skips Branch B. A, C, E, G, H and I take no BPA pattern id.
| Branch | The user asks to… | Read first, and follow |
|---|---|---|
| A — OSGi configs → Cloud Manager | scan config files; create or set up Cloud Manager environment secrets or variables; move passwords or secrets out of OSGi / .cfg.json / ui.config; or mentions $[secret:] / $[env:] | references/osgi-cfg-json-cloud-manager.md immediately: the product rules and the workflow are in that file. A short prompt is enough; the user need not name the file. |
| B — Java / HTL / BPA pattern | fix one pattern, from a BPA CSV, from CAM, or in files they name | The steps under Branch B below |
| C — Template modernization | migrate static templates to editable templates ("create editable templates", "generate /conf templates", "static to editable", "parsys to container"); generate AEM Modernize Tools rules (structure / component / policy rewrite rules) | template-modernization-context.md, then per template editable-template-creation.md and aem-modernization.md, then template-modernization-validation.md |
D — Legacy UI (lui, cdw) | convert Classic UI / ExtJS dialogs; upgrade Coral 2 dialogs; migrate custom ExtJS widgets; fix LUI or CDW findings; or mentions cq:Dialog / xtype / cq:Widget | The steps under Branch D below |
| E — Dispatcher conversion | convert or migrate an AMS / on-premise Dispatcher configuration | references/dispatcher/flow.md: six phases around Adobe's dispatcher-converter. HARD STOP on filter-acl-loss. Do not present the result as done on validation failure. |
F — Oak index (oakIndex, beta) | fix Oak index findings; convert _oak_index definitions | references/oak-index.md: six steps around Adobe's index-converter. Compute the next free -custom-N, never assume -custom-1. Flag a datatype mismatch as needs_manual_review; do not apply it silently. Tell the user that the output needs a careful review. |
| G — Validate a migration (beta) | validate, verify or smoke-test migrated code on the local Cloud SDK | references/validation/validate-migration.md. It never edits customer source; a failure goes back to the branch that owns the pattern. |
| H — Asset workflow migration | migrate DAM asset workflows (DAM Update Asset customizations, asset workflow launchers, custom asset process steps, ImageMagick CommandLineProcess renditions); or mentions Adobe's Asset Workflow Migration Tool / wf-migrator / aem-cloud-migration | references/asset-workflow/flow.md: four steps around Adobe's wf-migrator, which makes every change. The skill runs it and guides the review; it never edits project files itself. Never present a failed run as done. |
| I — Repository restructuring (beta) | restructure the project for AEM as a Cloud Service; split a content package into code (ui.apps) and content (ui.content); create ui.config or the all package; or mentions the Repository Modernizer | references/repo-structure/flow.md: five steps around Adobe's repository-modernizer. The plan review with the user is required. The tool's output is a copy: check it, then adopt it on a branch. Run this before the other branches when the project has no ui.config or all. |
Branch B — Java / HTL / BPA pattern migration:
-
Read
{code-assessment}/SKILL.md— critical rules, Java baseline links, Pattern Guides table, Manual Pattern Hints. -
Read the pattern guide (or reference) for the single active pattern:
scheduler→{code-assessment}/scheduler/SKILL.md(pattern guide)resourceChangeListener→{code-assessment}/resource-change-listener/SKILL.md(pattern guide)replication→{code-assessment}/replication/SKILL.md(pattern guide)eventListener/eventHandler→{code-assessment}/event-migration/SKILL.md(pattern guide — both JCR and OSGi Event Admin paths)assetApi→{code-assessment}/asset-manager/SKILL.md(pattern guide)htlLint→{code-assessment}/references/data-sly-test-redundant-constant.md(reference — HTL lint is a single shared reference, not a dedicated pattern guide)vault-package-dependencies→ references/vault-package-dependencies.md (reference — heuristicpom.xmlscan)guavaCache→ references/guava-cache.md (reference — Guava cache → Caffeine)inputStream→ references/input-stream.md (reference — triage of theDG/java.io.inputstreamadvisory; detection isscripts/input-stream-runner.js, not the code-assessment analyzer)
The last three live under
migrationonly, not undercode-assessment: these shapes occur only in code carried over from legacy AEM. -
When code uses SCR,
ResourceResolver, or console logging, read{code-assessment}/references/scr-to-osgi-ds.mdand{code-assessment}/references/resource-resolver-logging.md(or the hub{code-assessment}/references/aem-cloud-service-pattern-prerequisites.md).
Do not transform Java or HTL until the pattern guide (or reference) is read (branch B). Branch A does not require {code-assessment} pattern guidance.
Behavior pinning (before-eligible Java patterns). For guavaCache, scheduler, resourceChangeListener, and eventListener/eventHandler, Step 5 pins a one-per-finding characterization test around each edit (green before → transform → green after). Rules and skeletons: references/characterization-tests.md.
Branch D — Legacy UI Migration (legacy-ui/ sub-folders):
- Dialog findings (
lui, sub-typeslegacy.dialog.classicandlegacy.dialog.coral2only): read dialog/context.md (getBpaFindings('lui', …), filter to the dialog sub-types, skip all others with a note); convert with extjs-to-coral3.md (convert-extjs) or coral2-to-coral3.md (upgrade-coral2); validate with dialog/validation.md. - Custom widget findings (
cdw): read cdw/context.md (getBpaFindings('cdw', …), inventory the xtypes); per xtype apply cdw/conversion.md (a mapping, or a scaffolded Granite UI component); validate with cdw/validation.md.
Prerequisites
- Project source and Maven/Gradle build
- BPA CSV or MCP access optional but recommended
- For htlLint:
ui.appsor equivalent content package with.htmlHTL templates
BPA findings
Get targets with getBpaFindings from ./scripts/bpa-findings-helper.js; do not reimplement collection logic by hand unless the helper is unavailable. The flow, the call, collection caching and the batching rules: references/bpa-helper.md.
- Two sources, two caches. With MCP configured (
mcpFetcher+projectId) the first call fetches from CAM and caches; with a BPA CSV the first call parses it and caches. With neither, the helper reportsno-source: ask the user for one. htlLintis not in a BPA CSV. It uses proactivergdiscovery; see htlLint flow.- CAM: the user must explicitly confirm the project first. Recipes, schemas, retries and the 500-target cap: references/cam-mcp.md.
MCP errors and fallback
Critical: On MCP failure, stop the workflow immediately and give the user the exact tool error message (verbatim), including "not found" / 404-style project errors. Do not continue with migration steps, infer a different CAM project from the workspace, or switch to manual/local migration on your own.
Exception: enablement restriction errors (prefix documented in references/cam-mcp.md) must be shown verbatim with no paraphrase and no automatic fallback until the user addresses them.
After stopping, you may summarize what failed in plain language and re-show the projects. Continue only when the user explicitly directs the next step: a CAM project id or name from the list, a BPA CSV path, or specific Java files for the manual flow. Retries and error categories are in references/cam-mcp.md; still no silent fallback. Never hide tool errors from the user.
Optional prompt after stop (user must reply): "Reply with the CAM project to use (id or name from the list), a path to your BPA CSV, or the Java files for a manual migration."
Workflow
Step 0: Migration runbook (review / scan entry point)
When the user opens with a broad review/scan request ("review my code for AEMaaCS migration", "scan my project for AEM migration") and does not name a single pattern, generate a read-only migration runbook before any apply work. It is one command; do not read the generator's source:
node scripts/runbook-generator.js <workspaceRoot> --out ./migration-runbook.md --cache ./migration-runbook.json
Add --csv <bpa.csv> for a BPA CSV. For CAM, for an LLM scan when the command prints ⚠️ Needs LLM scan: …, for how each pattern is detected, and for what to tell the user afterwards: references/runbook.md. Read it before you run a runbook with CAM data.
Skip Step 0 when the user names a specific pattern up front: go straight to the relevant apply flow.
One pattern per session
If the user asks to fix everything or BPA mixes patterns, ask which pattern first. Prefer one commit per pattern session.
Step 1: Pattern id
First check the branches other than B (see Required delegation): A (OSGi configs), C (templates), D (Legacy UI: lui for dialogs, cdw for widgets), E (Dispatcher), F (Oak index, oakIndex), G (validate), H (asset workflows), I (repository restructuring).
Otherwise map the request to a pattern id: scheduler, resourceChangeListener, replication, eventListener, eventHandler, assetApi, htlLint, lui, cdw, inputStream. If unclear, use Manual Pattern Hints in {code-assessment}/SKILL.md or ask the user to pick one of those.
Step 2: Availability
If the id is missing from the code-assessment catalog ({code-assessment}/references/patterns.md), say the pattern is not supported yet. Exception: the migration-only references routed in Branch B step 2 (vault-package-dependencies, guavaCache, inputStream) are supported even though they aren't in that catalog.
Step 3: Targets
In this order, and stop at the first that has findings for the active pattern:
- The runbook cache,
./migration-runbook.json: reusefindingsByPattern[<pattern>]and tell the user that you do. Heuristic entries (htlLint,osgiConfig) are candidates: re-confirm each before editing. getBpaFindingsfor BPA patterns (scheduler,resourceChangeListener,replication,eventListener,eventHandler,assetApi,lui,cdw). If MCP fails, obey MCP errors and fallback.- The pattern's own discovery:
rgforhtlLint;scripts/input-stream-runner.jsforinputStream, which always runs once because BPA names classes and not lines; the inventory of Branch E fordispatcherConversion.
Every path serves five findings per batch. How to read the cache, the envelope, and the rules for lui, inputStream, htlLint and osgiConfig targets: references/targets.md. Read it before the first batch.
Step 4: Read before edits
STOP. Read {code-assessment}/SKILL.md and the pattern guide (or reference) for the active pattern — see Branch B step 2 above for the pattern → file routing table.
Step 5: Process the batch
For each finding in the returned batch only (up to 5):
- Resolve the target inside the IDE workspace (see Workspace scope (IDE)).
- Pin behavior first (before-eligible patterns only). If the active pattern is before-eligible in references/characterization-tests.md (
guavaCache,scheduler,resourceChangeListener,eventListener/eventHandler), write one characterization test for this finding and run it green before editing — this pins current behavior. Follow that file's efficiency contract exactly: one fill-in skeleton, one attempt, skip-fast withpin-skip: <reason>. Never debug a test. All other patterns (includingreplication,assetApi, and every non-Java pattern) skip this step. - Read source → classify with the pattern guide (or reference) → apply steps in order → check lints.
- Re-run the pinned test (only if step 2 pinned one). Green → behavior preserved, record
pinned. Red after the edit → a real regression: revert this finding's edit, recordpin-fail → reverted, and move on — do not retry or edit the test. - Next file.
Step 6: Report batch and wait
After finishing the batch, summarise for this batch only: paging.returned of paging.total processed (with class names), files touched, and any skips/failures. For before-eligible patterns, add each finding's pin outcome (pinned | pin-skip: <reason> | pin-fail → reverted) per references/characterization-tests.md — omit this line entirely for patterns that are not before-eligible. If paging.hasMore, tell the user "Processed batch of N (offset {offset}–{offset + returned − 1} of {total}). Reply continue for the next batch, or name specific classes."; otherwise say the pattern is done and move to the session report.
Then stop and wait — resume only when the user explicitly asks, per the Batched-processing rules.
Manual flow (no BPA)
User-named files → classify (code-assessment Manual Pattern Hints or ask) → confirm the pattern guide or reference exists → read {code-assessment}/SKILL.md + the pattern guide (or reference) — see Branch B step 2 routing — → transform → report.
htlLint flow
htlLint does not use BPA CSV or CAM/MCP. Its three steps (read the reference, discover with rg, fix and report): references/htl-lint.md.
Batched processing (batch size 5)
Findings come in batches of 5, whatever the source. The fetch (MCP call or CSV parse) happens once and is cached; each further batch is a slice of the cache.
- One batch per call: process, report, stop. Never pre-fetch, merge batches, or pass
limit: null. - The next offset is
result.paging.nextOffset. Never computeoffset + limityourself. - Done when
paging.hasMore === false.
The full rules and an example exchange: references/bpa-helper.md.
Quick reference
The source priority for BPA patterns and the snippets to show the user: references/bpa-helper.md.
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/aem/cloud-service
- Author
- Adobe
- Category
- Aem
- License
- Apache-2.0
- Keywords
- adobe, aem, aemaacs, cloud-service, dispatcher, component, workflow, rde, code-assessment, migration, content-distribution
More from adobe/skills
All 19- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1
- aem-eds-personalizationv1.0.0
- aem-forms-edge-delivery-servicesv1.0.1
- aem-project-managementv1.0.1
- app-builderv1.0.0
- commerce-app-management
- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0
- stardustv0.39.4
- webv1.0.0
- workfrontv2.0.0
- adobe-analyticsv1.0.0
- adobe-cjav1.0.1
- adobe-for-developersv1.0.0
- aem-6-5-ltsv1.0.0