AEM as a Cloud Service — Best Practices

Platform guidance for AEM as a Cloud Service: Java/OSGi (what to use, what to avoid, how to refactor legacy patterns) and HTL (component

.html

templates, Cloud SDK HTL lint).

This skill holds the pattern transformation modules (

references/*.md

). They ship with the aem-cloud-service
plugin; use this skill without the migration skill for greenfield or maintenance work that only needs these references. Use migration when you need BPA/CAM orchestration on top.

Quick pick: Open the Pattern Reference Modules table below → jump to the matching

references/<file>.md

→ read it fully before editing. For Java: Felix SCR, resolvers, or logging, use Java / OSGi baseline links first when those appear in the same change set.

When to Use This Skill

Use this skill when you need to:

Apply AEM as a Cloud Service constraints to Java/OSGi code (new or existing)
Refactor legacy Java patterns into supported APIs (same modules migration uses)
Follow consistent rules across schedulers, replication, JCR observation listeners (
```
eventListener
```
), OSGi event handlers (
```
eventHandler
```
), and DAM assets
Fix HTL (Sightly) issues from the AEM Cloud SDK build, especially
```
data-sly-test: redundant constant value comparison
```
Read step-by-step transformation and validation checklists for a specific pattern

For BPA/CAM orchestration (collections, CSV, MCP project selection), use the migration
skill (

skills/aem/cloud-service/skills/migration/

Pattern Reference Modules

Each supported pattern has a dedicated module under

references/

relative to this

SKILL.md

Pattern / topic	BPA Pattern ID	Module file	Status
Scheduler	`scheduler`	`references/scheduler.md`	Ready
Resource Change Listener	`resourceChangeListener`	`references/resource-change-listener.md`	Ready
Replication	`replication`	`references/replication.md`	Ready
Event listener (JCR observation)	`eventListener`	`references/event-migration.md`	Ready
Event handler (OSGi Event Admin)	`eventHandler`	`references/event-migration.md`	Ready
Asset Manager	`assetApi`	`references/asset-manager.md`	Ready
Felix SCR → OSGi DS	—	`references/scr-to-osgi-ds.md`	Ready
ResourceResolver + SLF4J	—	`references/resource-resolver-logging.md`	Ready
HTL: `data-sly-test` redundant constant	— (HTL lint)	`references/data-sly-test-redundant-constant.md`	Ready
(Prerequisites hub)	—	`references/aem-cloud-service-pattern-prerequisites.md`	—

Event listener vs event handler (not the same): eventListener
is JCR observation — the JCR API for repository change callbacks (

javax.jcr.observation.EventListener

onEvent

). eventHandler
is OSGi Event Admin — whiteboard-style OSGi events (

org.osgi.service.event.EventHandler

handleEvent

). Both migrate via references/event-migration.md
(Path A vs Path B). resourceChangeListener
is separate: Sling ResourceChangeListener
, module references/resource-change-listener.md
.

Before changing code for a pattern: read the module for that pattern in full. Modules include classification criteria, ordered transformation steps, and validation checklists.

Java / OSGi baseline (same skill; no separate installables)

SCR→DS and

ResourceResolver

/logging are reference modules under

references/

— not separate skills. Read them when relevant instead of re-embedding the same steps inside each pattern file.

Hub:

references/aem-cloud-service-pattern-prerequisites.md

Modules:

references/scr-to-osgi-ds.md

references/resource-resolver-logging.md

Critical Rules (All Patterns)

These rules apply to every pattern module. Violation means incorrect migration or unsafe Cloud Service code.

READ THE PATTERN MODULE FIRST — never transform code without reading the module
READ
```
scr-to-osgi-ds.md
```
and
```
resource-resolver-logging.md
```
when SCR,
```
ResourceResolver
```
, or logging are in scope (pattern modules link via the prerequisites hub; do not duplicate long guides inline)
DO preserve environment-specific guards (e.g.
```
isAuthor()
```
run mode checks)
DO NOT change business logic inside methods (Java) or logical show/hide intent (HTL) unless the module explicitly allows it
DO NOT rename classes unless the pattern module explicitly says to
DO NOT invent values — extract from existing code
DO NOT edit files outside the scope agreed with the user (e.g. only BPA targets or paths they named)
DO keep searches, discovery, and edits for the customer's AEM sources inside the IDE workspace root(s) currently open; DO NOT grep or walk directories outside that boundary to find Java unless the user explicitly points there

Manual Pattern Hints (Classification)

When no BPA list exists, scan imports and types to pick a module:

Look for	Pattern
`org.apache.sling.commons.scheduler.Scheduler` or `scheduler.schedule(` with `Runnable`	`scheduler`
`implements ResourceChangeListener`	`resourceChangeListener`
`com.day.cq.replication.Replicator` or `org.apache.sling.replication.*`	`replication`
JCR observation: `javax.jcr.observation.EventListener` , `onEvent(EventIterator)` , `javax.jcr.observation.*`	`eventListener`
OSGi Event Admin: `org.osgi.service.event.EventHandler` , substantive `handleEvent` (resolver/session/node work)	`eventHandler`
`com.day.cq.dam.api.AssetManager` create/remove asset APIs	`assetApi`
`org.apache.felix.scr.annotations`	read `references/scr-to-osgi-ds.md` (often combined with a BPA pattern)
`getAdministrativeResourceResolver` , `System.out` / `printStackTrace`	read `references/resource-resolver-logging.md`
HTL: build warning `data-sly-test: redundant constant value comparison` , or `.html` under `ui.apps` / `jcr_root` with bad `data-sly-test`	read `references/data-sly-test-redundant-constant.md`

If multiple patterns match, ask which to fix first.

Relationship to Migration

The migration
skill defines one-pattern-per-session workflow, BPA/CAM/MCP flows, and user messaging. It delegates all detailed transformation steps to this skill's

references/

modules. It uses a {best-practices}
repo-root path alias to this folder (see its

SKILL.md

). Keep platform truth here; keep orchestration there.

best-practices

NPX Install

Tags

SKILL.md Content