adobe avatar

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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.

Contents

Discovered from source

Skills 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:

  1. Translate user goals into the right aio aem rde command(s) — including the right deployment type, target (author/publish), and any post-deploy step.
  2. Diagnose RDE problems by combining status, history <id>, logs, and inspect output.
  3. Guide setup/configuration (org/program/env), local vs. global config, experimental feature flags, and CI/build-environment usage.
  4. 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 for aio / 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 commands
    • aem:rde:inspect — experimental, opt-in
    • aem:rde:snapshot — experimental, opt-in
  • Both notations work and are equivalent: aio aem rde … and aio aem:rde:….

Configuration model — get this right first

Every RDE command needs three IDs from Cloud Manager:

Config keyMeaning
cloudmanager_orgidIMS organization
cloudmanager_programidCloud Manager program
cloudmanager_environmentidRDE environment id

Two ways to set them:

  • Interactive (recommended for humans): aio login then aio aem rde setup. Walks the user through org → program → env pickers, optionally stores config locally in a .aio file in the current working directory.
  • Scripted / CI (build envs): aio config:set cloudmanager_orgid <id> etc. Strongly prefer the -l / --local flag 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:

CommandOne-liner
aio aem rde setupInteractive org/program/env picker
aio aem rde statusShow 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 logsTail AEM logs with logger-level filters and highlight
aio aem rde restartRestart author + publish
aio aem rde resetReset env to base; long-running, can keep mutable content

Experimental — aem:rde:inspect:*:

CommandPurpose
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 enableTurn on request logging (per-target)
aio aem rde inspect request-logs disableTurn off request logging

Experimental — aem:rde:snapshot:*:

CommandPurpose
aio aem rde snapshotList 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/delete deploy to both by default; inspect/logs default to author.
  • --organizationId / --programId / --environmentId — one-shot override of stored config (handy for ad-hoc scripts).
  • -q, --quiet — no log output, no prompts. Pair with --json for machine consumption.
  • --json — JSON result (not supported by setup, logs, inspect:request-logs:enable/disable — they declare enableJsonFlag: 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:

InputGuessed type
*.jarosgi-bundle
*.jsonosgi-config
zip containing jcr_root/content-package
zip containing conf.dispatcher.d/dispatcher-config
zip with dist/ + package.jsonfrontend
zip with any *.yaml entryenv-config
*.xml with --pathcontent-xml
other file with --pathcontent-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/--target defaults to author; pass publish to tail the publish leg.
  • AEM allows only a small number of concurrent log configs per env; on 405 the 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):

CodeMeaning
1Generic / uncaught error
2Configuration error
3Validation error in flags or arguments
4Deployment error
5Internal error — retry may help
40Deployment-not-fully-performed (sometimes acceptable mid-pipeline)

Diagnostic playbook (in order):

  1. aio aem rde setup --show — confirm pointing at the right env.
  2. aio aem rde status — is the env even Ready? What's actually deployed?
  3. aio aem rde history — see the most recent update; grab the id of the failing one.
  4. aio aem rde history <id> — full per-instance log of that update.
  5. aio aem rde logs -e "" -w "" — tail errors+warnings for new symptoms.
  6. 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, suggest install. Point out --restart only if needed. Reference deployment-types.md only 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 (or aio logout + setup if they're switching IMS orgs). Recommend -l storage 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 status first; inspect osgi-bundles/osgi-components/osgi-configurations for OSGi-level detail.
  • "How do I script this in CI?" — Recommend aio config:set -l for the three IDs, --quiet --json for commands, and warn against setup (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 .aio file, experimental-feature flags, notifications.
  • references/deployment-types.md — Detailed guidance on each --type, source-path conventions, --path handling for content-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 IntentSkillPath
Create a workflow model, add steps, design OR/AND splits, configure variablesModel Designworkflow-model-design/SKILL.md
Implement a custom WorkflowProcess step, ParticipantStepChooser, OSGi service registrationDevelopmentworkflow-development/SKILL.md
Start a workflow from code, HTTP API, Timeline UI, Manage PublicationTriggeringworkflow-triggering/SKILL.md
Configure a launcher, auto-start on asset upload, overlay OOTB launcherLaunchersworkflow-launchers/SKILL.md
Workflow stuck, failed step, missing Inbox task, stale instances, thread pool exhaustion, purgeDebuggingworkflow-debugging/SKILL.md
Classify a workflow incident, determine required logs, Splunk queries, data gathering checklistTriagingworkflow-triaging/SKILL.md
End-to-end lifecycle or requests spanning multiple concernsOrchestratorworkflow-orchestrator/SKILL.md

How to Use

  1. Match the user's request to one row in the Intent Router table above.
  2. Read the linked SKILL.md for that specialist skill.
  3. Follow the workflow, references, and output contract defined in that skill.
  4. 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

ConstraintDetail
No JMXNo retryFailedWorkItems, countStaleWorkflows, restartStaleWorkflows, purgeCompleted via JMX
/libs is immutableNever 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 usersAlways use workflow-process-service sub-service; never admin credentials
OSGi annotationsDS R6 (@Component, @Reference from org.osgi.service.component.annotations)
Deploy viaCloud Manager pipeline — no Package Manager in production

Specialist 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

SourceWhenTarget versions (deps)
User-namedthe user names files or coordinatesuser-supplied
Discoverthe user asks to scan, or names no filesuser-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

  1. User named files / coordinates → run the runbook in with_findings mode against those paths.
  2. "Scan my repo" / no files named → run the runbook in discover mode (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 / sawExpert skill
"update aem sdk", "upgrade mockito", stale <version> or ${property} in pomoutdated-dependencies/
"fix @Inject", "modernize Sling Models", javax.inject.Inject on @Model fieldsinject-in-sling-model/
"add HTTP timeouts", "outbound/external call has no timeout", HttpClient / HttpClients / OkHttpClient built without a timeoutoutbound-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 querytuning-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 coderequest-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 configsremove-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 / sawExpert skillBPA pattern ID
org.apache.sling.commons.scheduler.Scheduler or scheduler.schedule( with Runnablescheduler/scheduler
implements ResourceChangeListener, lightweight listener + JobConsumerresource-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, removeAssetForBinaryasset-manager/assetApi
HTL build warning data-sly-test: redundant constant value comparisonreferences/data-sly-test-redundant-constant.mdhtlLint (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; migration continues 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 bootstrap AGENTS.md/CLAUDE.md. If you can't ask (a headless or non-interactive run), stop after the plan and say that nothing was changed. When migration hands 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-api is plugin-driven and needs Maven Central (to resolve aemanalyser-maven-plugin and, 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 skipped with 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 the migration skill" 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 Replicator API
  • 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:

TaskSub-SkillFile
Programmatically publish/unpublish contentReplication APIreplication/SKILL.md
Monitor distribution events and lifecycleSling Distribution Eventssling-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:

  1. Replication API: com.day.cq.replication

  2. Sling Distribution API: org.apache.sling.distribution

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

  1. Your code calls Replicator.replicate() to publish content
  2. Sling Distribution packages content and fires AGENT_PACKAGE_CREATED event
  3. Package is queued and AGENT_PACKAGE_QUEUED event fires
  4. Package is sent to Adobe Developer pipeline and AGENT_PACKAGE_DISTRIBUTED event fires
  5. Target tier imports content and IMPORTER_PACKAGE_IMPORTED event fires
  6. 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

ConstraintLimitImpact
Paths per API call (recommended)100Transactional guarantee; system auto-splits above this
Payload size10 MBExcluding 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

FeatureAEM 6.xAEM Cloud Service
Replication APIcom.day.cq.replication.Replicator✅ Same API
Replication agentsManual configuration✅ Automatic (managed by Adobe)
Transport mechanismDirect JCR replication✅ Sling Distribution via Adobe pipeline
Preview tierNot available✅ Available (requires agent filtering)
Distribution eventsLimited✅ Full lifecycle via org.apache.sling.distribution.event
Agent configurationManual 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

  1. Use the right API: Replication API for publishing, Distribution events for monitoring
  2. Respect rate limits: ≤100 paths for transactional guarantee
  3. Handle failures: Always catch ReplicationException, monitor AGENT_PACKAGE_DROPPED events
  4. Use service users: Never use admin credentials
  5. Filter events appropriately: Only listen to events you need
  6. Validate permissions: Call replicator.checkPermission() before replication
  7. Publish only what's needed: Avoid unnecessary bulk operations

Troubleshooting

Replication Issues

IssueSolution
ReplicationExceptionCheck service user has crx:replicate permission
Content not on target tierVerify agent filter, check replication status
"Too many paths" errorUse ≤100 paths for transactional guarantee, or pass all paths — system auto-splits

Event Handling Issues

IssueSolution
Event handler not firingVerify event topic constant matches exactly
Missing event propertiesAlways null-check event properties
Handler slowing distributionUse async job processing, don't block

Detailed Documentation

For detailed examples, code samples, and advanced usage:

References

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?

StatusAction
File missing or configured: falseStop 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: trueRead 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

StepAction
0Configuration validation (do this first — see above)
1Extract & validate component name
1.5Component extension decision (if extending)
2Gather requirements & confirm dialog specification
2.3Figma design fetch (if Figma URL provided)
3Create all component files
3.11Dependency verification (required for servlets)
4Completion summary

Step 0: Configuration Validation

0.1 Read Configuration

  1. Read .aem-skills-config.yaml from the project root
  2. Check that configured: true
  3. Read project, package, and group values

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

  1. Read references/aem-conventions.md for file structure templates, naming conventions, and patterns

0.4 Project State Analysis (after configuration validated)

  1. Check Component Name Uniqueness - Look in /apps/[project]/components/
  2. Check Model Class Conflicts - Look in core/src/main/java/[package-path]/models/
  3. 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 SaysMaps To
imagecore/wcm/components/image/v3/image
teaser, cardcore/wcm/components/teaser/v2/teaser
text, richtextcore/wcm/components/text/v2/text
title, headingcore/wcm/components/title/v3/title
listcore/wcm/components/list/v4/list
button, ctacore/wcm/components/button/v2/button
navigation, navcore/wcm/components/navigation/v2/navigation
container, sectioncore/wcm/components/container/v1/container
accordioncore/wcm/components/accordion/v1/accordion
tabscore/wcm/components/tabs/v1/tabs
carouselcore/wcm/components/carousel/v1/carousel
embed, videocore/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 RequestAction
"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 ComponentExporter interface
  • Add resourceType to @Model annotation
  • Use sling:hideResource in 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. Load references/extending-core-components.md for 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/...):

  1. Parse the URL to extract fileKey and nodeId (see references/figma-design-rules.md Rule 1)
  • Convert - to : in the node-id query parameter
  • Use branchKey as fileKey for branch URLs
  1. **Call **get_design_context via the plugin-figma-figma MCP 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" } }
  2. Extract design tokens from the response — colors, fonts, sizes, spacing, layout (see Rules 3-4)
  3. 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 IndicatesServlet Required?
External API integrationYes (GET)
Dynamic data loadingYes (GET)
Form submissionYes (POST)
Search/filterYes (GET)
Static dialog contentNo

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/fileupload when 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 provided scope 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 SaysGranite Resource Type
Textfieldgranite/ui/components/coral/foundation/form/textfield
Textareagranite/ui/components/coral/foundation/form/textarea
Richtext, RTEcq/gui/components/authoring/dialog/richtext
Pathfield, Pathgranite/ui/components/coral/foundation/form/pathfield
Image, PhotoEmbed Core Image component (see references/htl-patterns.md Image Handling section). Do not use fileupload for image rendering.
Fileupload, File Uploadcq/gui/components/authoring/dialog/fileupload (for non-image files: PDFs, documents)
Multifieldgranite/ui/components/coral/foundation/form/multifield
Checkboxgranite/ui/components/coral/foundation/form/checkbox
Select, Dropdowngranite/ui/components/coral/foundation/form/select
Numberfieldgranite/ui/components/coral/foundation/form/numberfield
Datepickergranite/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:

CreatingLoad Reference
Any component.aem-skills-config.yaml (project root, load first — see Configuration Gate Check), then references/aem-conventions.md
Dialog XMLreferences/dialog-patterns.md
HTL Templatereferences/htl-patterns.md
Sling Modelreferences/model-patterns.md, references/java-standards.md
Unit Testsreferences/test-patterns.md
Clientlibsreferences/clientlib-patterns.md
Extending Core Componentreferences/extending-core-components.md
Extending Core Component — worked example & checklistsreferences/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 Servletreferences/sling-servlet-standards.md
Core Component patternsreferences/core-components.md
No Hallucination rulesreferences/no-hallucination-rules.md
Figma design integrationreferences/figma-design-rules.md
Troubleshootingreferences/troubleshooting.md
Examplesreferences/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 IntentSkillPath
Create, modify, review, or harden dispatcher config files (.any, vhost, rewrite, cache, filter)Config Authoringconfig-authoring/SKILL.md
Conceptual questions (statfileslevel, filter rules, URL decomposition, cache invalidation, rewrite behavior, security headers)Technical Advisorytechnical-advisory/SKILL.md
Investigate runtime incidents, failures, probe regressions, or cache anomaliesIncident Responseincident-response/SKILL.md
Optimize cache efficiency, latency, and throughputPerformance Tuningperformance-tuning/SKILL.md
Security audit, threat model, exposure control, header hardeningSecurity Hardeningsecurity-hardening/SKILL.md
End-to-end lifecycle (design → implement → validate → release → incident) or requests spanning multiple concernsWorkflow Orchestratorworkflow-orchestrator/SKILL.md

How to Use

  1. Match the user's request to one row in the Intent Router table above.
  2. Read the linked SKILL.md for that specialist skill.
  3. Follow the workflow, references, and output contract defined in that skill.
  4. 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 validation
  • lint — deep/order-aware linting
  • sdk — SDK check-files and diff-baseline
  • trace_request — trace a request through dispatcher
  • inspect_cache — inspect cache state
  • monitor_metrics — runtime metrics
  • tail_logs — log tailing

Specialist 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:

  1. Check whether AGENTS.md exists at the workspace (repository) root.
  2. If it exists → skip this skill entirely and continue with the user’s request.
  3. 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.md and CLAUDE.md if 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-assessment plans 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

  1. Look for AGENTS.md at the workspace root. If it exists → skip, move on.
  2. Verify this is an AEM Cloud Service project: root pom.xml exists and references com.adobe.aem:aem-sdk-api or aem-project-archetype or 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 leading aem-, 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:

SignalAdd-on / variant
pom.xml depends on cif-connector or aem-core-cif-componentsCIF (Commerce)
ui.frontend/package.json contains react or @adobe/aem-react-editable-componentsReact SPA
ui.frontend/package.json contains @angular/core or @adobe/aem-angular-editable-componentsAngular SPA
ui.frontend has no clientlib.config.js and pom.xml references frontend-maven-plugin but outputs no clientlibsDecoupled frontend
pom.xml depends on aem-forms-* or forms.coreAEM Forms
Module ui.frontend.react.forms.af existsHeadless Forms
pom.xml uses precompiled-scripts-providerPrecompiled 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 the dispatcher directory exists.
  • it.tests / ui.tests — only include if they exist.
d. Build commands
  • Include frontend commands (npm run build, npm start) only if ui.frontend exists.
  • Include dispatcher validate command only if dispatcher module exists.
  • For React/Angular SPA, note that npm start requires 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.md and CLAUDE.md in 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

FilePurpose
references/AGENTS.md.templateBase template with {{PROJECT_NAME}} placeholder and all default sections
references/module-catalog.mdModule descriptions, add-on descriptions, conditional resources — the source of truth for adapting the template

Rules

  • Never overwrite an existing AGENTS.md or CLAUDE.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):

SymbolPath
{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 filePath or 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.

BranchThe user asks to…Read first, and follow
A — OSGi configs → Cloud Managerscan 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 patternfix one pattern, from a BPA CSV, from CAM, or in files they nameThe steps under Branch B below
C — Template modernizationmigrate 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:WidgetThe steps under Branch D below
E — Dispatcher conversionconvert or migrate an AMS / on-premise Dispatcher configurationreferences/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 definitionsreferences/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 SDKreferences/validation/validate-migration.md. It never edits customer source; a failure goes back to the branch that owns the pattern.
H — Asset workflow migrationmigrate 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-migrationreferences/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 Modernizerreferences/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:

  1. Read {code-assessment}/SKILL.md — critical rules, Java baseline links, Pattern Guides table, Manual Pattern Hints.

  2. 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 — heuristic pom.xml scan)
    • guavaCache → references/guava-cache.md (reference — Guava cache → Caffeine)
    • inputStream → references/input-stream.md (reference — triage of the DG / java.io.inputstream advisory; detection is scripts/input-stream-runner.js, not the code-assessment analyzer)

    The last three live under migration only, not under code-assessment: these shapes occur only in code carried over from legacy AEM.

  3. When code uses SCR, ResourceResolver, or console logging, read {code-assessment}/references/scr-to-osgi-ds.md and {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):

Prerequisites

  • Project source and Maven/Gradle build
  • BPA CSV or MCP access optional but recommended
  • For htlLint: ui.apps or equivalent content package with .html HTL 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 reports no-source: ask the user for one.
  • htlLint is not in a BPA CSV. It uses proactive rg discovery; 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:

  1. The runbook cache, ./migration-runbook.json: reuse findingsByPattern[<pattern>] and tell the user that you do. Heuristic entries (htlLint, osgiConfig) are candidates: re-confirm each before editing.
  2. getBpaFindings for BPA patterns (scheduler, resourceChangeListener, replication, eventListener, eventHandler, assetApi, lui, cdw). If MCP fails, obey MCP errors and fallback.
  3. The pattern's own discovery: rg for htlLint; scripts/input-stream-runner.js for inputStream, which always runs once because BPA names classes and not lines; the inventory of Branch E for dispatcherConversion.

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):

  1. Resolve the target inside the IDE workspace (see Workspace scope (IDE)).
  2. 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 with pin-skip: <reason>. Never debug a test. All other patterns (including replication, assetApi, and every non-Java pattern) skip this step.
  3. Read source → classify with the pattern guide (or reference) → apply steps in order → check lints.
  4. 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, record pin-fail → reverted, and move on — do not retry or edit the test.
  5. 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 compute offset + limit yourself.
  • 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