Org Skills

aem-component-development

Builds Adobe Experience Manager Sites components — HTL with correct XSS contexts, Sling Models and JSON exporters, Core Components proxies and the delegation pattern, Granite UI dialogs and multifields, editable templates, policies and the Style System, i18n and component clientlibs.

Download .zip Raw Source
When agents use itUse this whenever the user writes or debugs an HTL .html file, a Sling Model or *Impl.java with @Model, @ValueMapValue, @ChildResource or @PostConstruct, a _cq_dialog or _cq_design_dialog .content.xml, a multifield, cq:editConfig, a proxy component with sling:resourceSuperType, a .model.json exporter, component groups or allowed components, i18n dictionaries, WCMMode placeholders, or Content and Experience Fragment components; or asks "how do I extend the Core Image or Teaser component", "why is my multifield empty in the model" or "why does my component render nothing". For tests use `aem-testing`. Also apply it when a styling variant request is really a Style System decision.

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-component-development -a github-copilot
# or with the org installer (adds .github/skills/aem-component-development):
npx -y github:AGCO-Global/org-skills add skill aem-component-development

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-component-development
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill aem-component-development -g

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

/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-development-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-component-development -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-component-development -a codex

Installs into Cursor's skills folder.

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

Installs into Gemini CLI's skills folder.

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

Nothing to install. Press Download .zip above, unzip it, and drop the aem-component-development 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 Component Development

Targets: AEM as a Cloud Service 2026.x with the platform-provided Core Components (Java 21), AEM 6.5 noted where different · Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-core-components/using/introduction

A component is a contract between authors, templates and code: the dialog is the authoring API, the Sling Model is the logic, HTL is a thin escaped view, and policies decide what is allowed where. Start from a Core Component and extend it; build from scratch only when no Core Component matches the content model — every hand-built component is a thing you maintain through every AEM release.

1. Decide first

Question Default Change when
Standard element (title, text, image, teaser, list, tabs, carousel) Proxy of a Core Component Never reference core/wcm/components/* from content directly
Core behaviour plus a few fields Proxy + extra dialog fields + delegating model Never by copying or subclassing a Core *Impl
Genuinely new content structure Custom component with its own interface and impl Still reuse Core HTL templates (placeholder, clientlib)
Look-and-feel variants Style System style groups on the policy Not a dialog dropdown, not a second component
Reusable authored block (header, promo) Experience Fragment Structured, channel-neutral data → Content Fragment
Where a setting lives Author dialog for per-instance content Template-wide decision → _cq_design_dialog (policy), read via currentStyle
Model adaptable SlingHttpServletRequest Resource-only for helpers and background code
Injection annotations @ValueMapValue, @ChildResource, @ScriptVariable, @OSGiService, @Self Never bare @Inject in a component model
Injection strategy DefaultInjectionStrategy.OPTIONAL + null handling Required injection makes a freshly dropped component render nothing

2. Proxy components and versioning

<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0"
    xmlns:jcr="http://www.jcp.org/jcr/1.0" jcr:primaryType="cq:Component"
    jcr:title="Title" componentGroup="Acme - Content"
    sling:resourceSuperType="core/wcm/components/title/v3/title"/>
  • Pin a specific Core version (v3); markup and exported JSON change between major versions, so upgrade one component at a time.
  • On Cloud Service the Core Components ship with the platform and update automatically — do not embed them in your package. Embed an explicit newer version only when you need a feature the platform has not rolled out yet, and remove it afterwards. On 6.5 you install and upgrade the package yourself against the compatibility matrix.
  • componentGroup drives the side panel; .hidden keeps helpers out of it. Allowed components are a policy setting on the container, never hard-coded in a template.

3. Sling Models

The full component model, the Core delegation pattern with @Via(type = ResourceSuperType.class), the .model.json shape (:type, :items, :itemsOrder) and Jackson shaping are in references/sling-models.md. The rules that do not change:

  • Adapt from the request; use injector-specific annotations; OPTIONAL strategy with null handling.
  • Compute once in @PostConstruct. HTL evaluates a getter every time it appears, including inside data-sly-repeat.
  • Expose an interface, keep *Impl internal, and never serialise Resource, Page or ValueMap through the exporter.
  • No queries, HTTP calls or resolver acquisition in a model — it runs on every render and every .model.json request.
  • Models with stable, meaningful property names are also what the Universal Editor writes back to; see aem-universal-editor before designing a component that must be editable in place.

4. HTL and XSS

<div data-sly-use.hero="com.acme.core.models.Hero"
     data-sly-use.tpl="core/wcm/components/commons/v1/templates.html"
     data-sly-test.hasContent="${!hero.empty}" class="cmp-hero">
  <h2 class="cmp-hero__title">${hero.title}</h2>
  <a data-sly-repeat="${hero.links}" class="cmp-hero__link" href="${item.url}">${item.label}</a>
</div>
<sly data-sly-call="${tpl.placeholder @ isEmpty=!hasContent, classAppend='cmp-hero'}"></sly>
  • HTL escapes by context in text and attribute positions. Inside <script>, <style>, event handlers and style attributes you must set the context (scriptString, styleString) — better still, pass values through data-* attributes and read them in JavaScript.
  • context='html' runs the value through the XSS/AntiSamy policy and is the right choice for RTE output. context='unsafe' disables escaping entirely and is a review blocker.
  • Resolve and map URLs in the model (.html extension, resourceResolver.map, Externalizer), not by string-building in HTL.
  • Include children with data-sly-resource, not data-sly-include of another component's script.
  • The Core placeholder template renders only in edit mode, so publish never shows empty boxes. Use wcmmode checks for authoring aids only — never for business logic.

5. Dialogs

  • One _cq_dialog/.content.xml per component, tabs via granite/ui/components/coral/foundation/tabs, property names starting with ./. When extending a Core dialog, overlay only the difference with sling:hideChildren, sling:orderBefore and sling:hideResource.
  • Multifields: composite="{Boolean}true" stores child nodes (item0, item1) read with @ChildResource; without it the field stores a String[]. The mismatch between the two is the usual cause of an empty multifield in the model.
  • _cq_design_dialog is the policy dialog: template-wide settings (heading levels, image widths, lazy loading) belong there and are read with @ScriptVariable private Style currentStyle.
  • Full XML for tabs, composite multifields, validators, Core dialog overlays and cq:editConfig is in references/dialogs.md.

6. Templates, policies, Style System, i18n

  • Editable templates live in /conf/<site>/settings/wcm/templates; policies in /conf/<site>/settings/wcm/policies. Static templates under /apps are legacy and unsupported for new work on Cloud Service.
  • Style System classes go on the component wrapper as BEM modifiers (cmp-teaser--dark) with identical markup across styles. cq:noDecoration removes the element that carries those classes — use it deliberately.
  • Site-wide values (a feature flag, an API path) belong in Context-Aware Configuration under /conf, not in a policy and not in every author dialog.
  • Static UI strings: ${'Read more' @ i18n} with dictionaries in /apps/<site>/i18n; new I18n(request) in Java. Authored strings are translated by the translation workflow instead.
  • Accessibility is part of the component contract: heading level exposed through the policy, alt text from DAM with an explicit "decorative" option, keyboard support and focus management for anything interactive.

7. Component client libraries

Put component CSS and JS in a component clientlib category (acme.components.hero) that the site clientlib embeds. Calling clientlib.js from each component's HTL produces duplicate, render-blocking requests. Author-only JavaScript goes in an author category loaded through the page policy or cq.authoring.*, never shipped to publish. Details in aem-frontend-development.

8. Deliverable format

1. Component node .content.xml (group, resourceSuperType)
2. _cq_dialog/.content.xml (+ _cq_design_dialog when the setting is template-wide)
3. Model interface + *Impl.java
4. HTL file, with the placeholder call
5. _cq_editConfig.xml when drag-and-drop or in-place editing is needed
6. Clientlib category and where it is embedded
7. Sample .model.json output
8. Tests to add (hand off to aem-testing)

Checklist

  • Content references a proxy, never core/wcm/components/*
  • No Core *Impl copied or subclassed; extension uses @Via(ResourceSuperType.class)
  • Model adapts from the request, uses injector-specific annotations and OPTIONAL strategy
  • Nothing expensive in getters; no queries or HTTP in the model
  • No context='unsafe'; context='html' only on RTE-sourced values
  • Multifield composite flag matches the Java injection
  • Template-wide settings are in the design dialog, not the author dialog
  • Visual variants come from the Style System, not a dialog dropdown
  • Empty component shows the Core placeholder in edit mode and nothing on publish
  • Exported JSON contains no Resource/Page objects and no internal paths
  • Component clientlib is embedded by the site clientlib, not included per component
  • Heading level, alt text and keyboard behaviour are covered

Anti-patterns

  • Copying a Core *Impl → delegate through ResourceSuperType; the impls are internal and change without notice.
  • @ context='unsafe' to make markup render → fix the value in the model; use html for RTE output.
  • Bare @Inject and required injection → injector-specific annotations with OPTIONAL and null handling.
  • A query or service call inside a getter → @PostConstruct, or a service with a cache.
  • A "variant" dropdown in the author dialog → Style System style groups on the policy.
  • Design settings in the author dialog → _cq_design_dialog, read via currentStyle.
  • afteredit="REFRESH_PAGE" on every component → only when the component truly cannot re-render itself.
  • Per-component data-sly-call of a clientlib → embed the category in the site clientlib.
  • Static templates or CRXDE edits in /apps on a new project → editable templates and the pipeline; /apps is immutable on Cloud Service.

Go deeper

  • references/sling-models.md — full model, delegation pattern, .model.json shape, Universal Editor readiness, a starter test.
  • references/dialogs.md — tabbed dialog XML, composite multifields, validators, Core dialog overlays, design dialog, cq:editConfig.
  • Sibling skills: aem-frontend-development for clientlibs and the Style System CSS, aem-backend-development for services the model calls, aem-universal-editor for in-place editing outside the page editor, aem-testing for tests, aem-code-review for reviews.

References

Deeper material the agent loads only when needed.