Org Skills

aem-architecture

Designs Adobe Experience Manager solution architecture and writes the decision record — Cloud Service vs 6.5, delivery model (HTL Sites, headless Content Fragments + GraphQL, Universal Editor hybrid, Edge Delivery Services), repository and package structure, MSM and translation, integrations, caching and personalization, identity, environments and NFRs.

Download .zip Raw Source
When agents use itUse this whenever the user asks how to structure an AEM project, whether to go headless or use Edge Delivery Services, compares AEMaaCS with AMS or on-prem, plans a multi-site or multi-language estate with blueprints, live copies or language copies, asks where code or content should live (/apps, /conf, /content, /content/dam, /var), about ui.apps vs ui.content or mutable vs immutable packages, about Adobe IMS product profiles or App Builder as an extension point, or needs an ADR or solution outline for AEM. Also apply it when a component or integration question hides a platform decision such as caching or authentication.

Install

Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.

npx skills add AGCO-Global/org-skills --skill aem-architecture -a github-copilot
# or with the org installer (adds .github/skills/aem-architecture):
npx -y github:AGCO-Global/org-skills add skill aem-architecture

Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.

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

Installs the aem-architecture-skills plugin, which bundles all AEM / Architecture skills and keeps them updated.

/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-architecture-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-architecture -a claude-code

Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.

Installs into .agents/skills/, which Codex reads.

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

Installs into Cursor's skills folder.

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

Installs into Gemini CLI's skills folder.

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

Nothing to install. Press Download .zip above, unzip it, and drop the aem-architecture folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.

The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.

Skill contents

AEM Architecture

Targets: AEM as a Cloud Service 2026.x, AEM 6.5 / 6.5 LTS noted where different · Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/overview/architecture

AEM architecture is mostly a caching and content-modelling problem wearing a CMS costume. Decide first how every page and API response gets cached at the CDN, how authors reuse content across sites and languages, and which platform limits are non-negotiable — components come last. Every decision belongs in a written record with its consequence, because the next team will otherwise re-derive it wrongly.

1. Decide first

Question Default Change when
Platform AEM as a Cloud Service Regulatory hosting, an unsupported native dependency, or a migration that is not funded → 6.5 LTS, with the constraint written into the ADR
Delivery model Per experience, from references/delivery-models.md Never by company-wide decree; mixing EDS + headless on one content model is normal
Visual editing on a decoupled front end Universal Editor Form-based editing is enough → Content Fragment editor, no instrumentation
New SPA Editor project Not an option — deprecated with AEMaaCS 2025.01 and 6.5.23 Only to maintain an existing SPA Editor site (P1/P2 and security fixes only)
Repository split /apps immutable, /conf + /content mutable, separate packages Never mixed — Cloud Service rejects mixed packages
Per-site variation MSM live copies from a blueprint Sites share only brand assets, not structure → independent trees
Personalization Client-side (Web SDK / a small JSON fetch) Edge or Sling Dynamic Include when the fragment must be server-rendered; uncached personalised HTML last
Custom platform extension Sling/OSGi in core Long-running, spiky, or third-party-facing work → Adobe Developer App Builder, off the publish tier
Identity for authors Adobe IMS with Admin Console product profiles mapped to AEM groups 6.5: SAML/LDAP; permissions always to groups, never to users

Cloud Service limits that shape designs: no custom run modes; no ESI at the Adobe CDN (server-side includes via mod_include do work); publish repository writes are lost when a pod recycles; no reverse replication; no custom replication agents; /apps and /libs read-only at runtime; config-pipeline files (including cdn.yaml) capped at 100 KB total.

2. Delivery model and content model

  • Pick the delivery model per experience using the table in references/delivery-models.md; record the choice, the date and the reason. Do not restate the table in the ADR — link it.
  • Content Fragments are structured, channel-neutral data (model-driven, queried by GraphQL or the Content Fragment Delivery OpenAPI). Experience Fragments are presentational and reusable layout. A CF used for layout, or an XF used as a data store, becomes unmaintainable within a release or two.
  • Model fragments for the data, not for the first channel that consumes them: fragment references over deep nesting, one model per real-world entity, and no presentation fields (cssClass, columnWidth).
  • Editable templates + policies in /conf decide allowed components, styles and image widths. Changing a policy changes every page using it, so name an owner in the ADR.

3. Repository, packages and environments

  • Module layout, filter.xml merge modes, the path table and the Cloud Service limits are in references/repository-layout.md. Two rules never move: mutable and immutable content ship in separate packages, and any filter root authors touch carries mode="merge".
  • Per-environment values come from $[env:NAME] / $[secret:NAME] in ui.config, never from a hostname in Git. Per-site values come from Context-Aware Configuration under /conf.
  • Custom Oak indexes follow one naming rule, owned by aem-backend-development: oak-index-naming.md in ../../development/aem-backend-development/references/. Do not invent a second convention in the ADR.
  • Environments: dev → stage → prod through Cloud Manager, plus RDEs for fast iteration. Stage mirrors prod and is the only place load tests mean anything.

4. Multi-site, translation and assets

  • Blueprint → live copies (MSM) for shared structure across markets; language masters → language copies for translation. A typical tree is /content/acme/language-masters/en → /content/acme/de/de.
  • Decide inheritance granularity up front: which components may break inheritance and who re-enables it. Uncontrolled cancel-inheritance is the main MSM failure mode, and it is invisible until a rollout silently skips markets.
  • Translate Content Fragments and Experience Fragments in the same translation project as the pages that use them; UI strings stay in i18n dictionaries in /apps.
  • Assets: metadata schemas and folder-level processing profiles; Dynamic Media with OpenAPI or web-optimized image delivery instead of dozens of static renditions. AEM Assets can also be the headless DAM for non-AEM channels — see aem-assets.

5. Integrations, identity and caching

  • Adobe Analytics and Target through Tags and the Web SDK with a documented data-layer contract; never a hardcoded vendor script in HTL. Commerce through CIF, with product data cached at the edge, not copied into the JCR.
  • External APIs through an OSGi service with connect and read timeouts, a fallback and a short cache (aem-backend-development). Per-user data is fetched client-side or at the edge so the page stays cacheable.
  • Authors: Adobe IMS, product profiles in the Admin Console mapped to AEM groups, permissions granted to groups and managed as repoinit where possible. Site visitors behind a login: see aem-security for CUGs and permission-sensitive caching.
  • Caching layers are CDN → Dispatcher → Publish, with an anonymous CDN hit ratio target above 90 %. Design URLs for caching: selectors and suffixes over query strings, one canonical URL per representation, no per-user data in HTML. Invalidation is by path and, on the Adobe CDN, by Surrogate-Key through the self-serve purge API. Rules and syntax belong to aem-dispatcher.

6. Deliverable format

## Context — goals, channels, sites × languages, traffic and NFR numbers
## Decisions — one row each: decision · options · choice · rationale · consequences
## Logical architecture — CDN / dispatcher / author / publish / integrations (text or Mermaid)
## Content model — templates, CF models, XF usage, /content and /content/dam trees
## Caching plan — per URL pattern: TTL · cacheable? · invalidation trigger · surrogate key
## Identity and access — IMS profiles → AEM groups; visitor auth; service users
## NFRs — peak req/s, hit-ratio target, TTFB/LCP budget, author concurrency, asset volume, RPO/RTO
## Risks and open questions — owner and due date each

Contract with sibling skills so the ADR does not re-derive them: caching rules → aem-dispatcher; queries and indexes → aem-backend-development; pipelines, env vars and RDE → aem-cloud-manager; GraphQL contract → aem-headless.

Checklist

  • Platform choice stated with the constraint that drove it, not a preference
  • Delivery model recorded per experience, linking references/delivery-models.md
  • No new SPA Editor work proposed
  • Mutable and immutable content are separate packages; author-owned filter roots use mode="merge"
  • Every URL pattern has a cacheability verdict, a TTL and an invalidation trigger
  • Personalization plan keeps anonymous HTML cacheable
  • MSM and translation model named, with an inheritance-breaking policy and an owner
  • Secrets and hostnames come from $[secret:] / $[env:]
  • NFRs are numbers, not adjectives
  • Cloud Service limits checked against the design (run modes, publish writes, ESI, 100 KB config)

Anti-patterns

  • "Headless because modern" while authors need page editing and MSM → pick per experience; a brief naming rollouts and workflows is a Sites brief.
  • Starting a new SPA Editor project → Universal Editor; SPA Editor is deprecated (2025.01).
  • One package containing /apps and /content → split into ui.apps and ui.content; Cloud Service rejects mixed packages.
  • <filter root="/content/acme"/> with no mode → mode="merge"; replace mode deletes authored content on deploy.
  • Per-user or cookie-dependent HTML on cacheable pages → move the personalised part to a client-side fetch.
  • Flat /content/dam folders with 100k+ assets → date- or product-based folder hierarchy in the thousands, set before ingestion starts.
  • Experience Fragments used as a data store → Content Fragments with a model.
  • Assuming 6.5 customisations lift and shift (custom replication agents, run modes, long publish jobs) → run the Best Practices Analyzer first (aem-cloud-migration).
  • NFRs written as "must be fast" → a TTFB and LCP budget plus a peak uncached request rate; autoscaling cannot rescue a low hit ratio.

Go deeper

  • references/delivery-models.md — the delivery-model comparison table and the deciding questions, shared by every AEM skill.
  • references/repository-layout.md — archetype modules, filter.xml merge modes, path-by-path rules and Cloud Service hard limits.
  • oak-index-naming.md in ../../development/aem-backend-development/references/ — the one index naming rule.
  • Sibling skills: aem-dispatcher for cache and CDN rules, aem-security for access design, aem-cloud-manager for pipelines and environments, aem-cloud-migration for 6.5 → Cloud, aem-headless and aem-edge-delivery-services for the two non-HTL models, aem-code-review for reviews.

References

Deeper material the agent loads only when needed.