Org Skills

aem-frontend-development

Builds Adobe Experience Manager Sites front-end code — the archetype ui.frontend webpack build, client libraries and categories, Style System CSS and design tokens, the responsive grid, JavaScript that survives the page editor, the Cloud Manager front-end pipeline and Site Themes, images and fonts, and Core Web Vitals on an AEM page.

Download .zip Raw Source
When agents use itUse this whenever the user edits ui.frontend, webpack config or clientlib.config.js (aem-clientlib-generator), a clientlib .content.xml with categories, embed, dependencies or allowProxy, js.txt or css.txt, /etc.clientlibs URLs, async/defer include attributes, BEM styles for the Style System, aem-Grid or cq:responsive breakpoints, HtmlPageItemsConfig, the data layer or tag manager on an AEM page, aem-site-theme-builder, npm run watch, or asks why fonts 404 only on publish, why a carousel breaks the page editor, or how Core Image renditions affect LCP. For tests use `aem-testing`.

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

Installs into Cursor's skills folder.

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

Installs into Gemini CLI's skills folder.

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

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

Targets: AEM as a Cloud Service 2026.x with the Maven AEM Project Archetype and platform Core Components; AEM 6.5 noted where different · Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/introduction/clientlibs

AEM front-end code runs in two very different places: a cached, CDN-fronted publish page, and an author page editor that swaps component DOM out from under you after every dialog save. Build one bundle per site, load it predictably, and write JavaScript that survives both without needing to know which one it is in.

1. Decide first

Question Default Change when
Build for an archetype project ui.frontend webpack → aem-clientlib-generator → ui.apps Theme changes ship far more often than Java → add a front-end pipeline module
Low-code site from a Site Template Site Theme repo + aem-site-theme-builder + front-end pipeline Never mix a pipeline theme with a clientlib copy of the same CSS
New app-like experience Headless or Edge Delivery Services with the Universal Editor See delivery-models.md in ../../architecture/aem-architecture/references/
New SPA Editor project Not an option — deprecated with AEMaaCS 2025.01 and 6.5.23 Only to maintain an existing SPA Editor site
Combining categories embed (one request) dependencies only when the other library must load as its own tag, first
Script loading defer async only for a library nothing else depends on — it destroys ordering
Visual variant Style System modifier class on the wrapper Never a new component, never !important against Core CSS
Number of bundles One site CSS + one deferred site JS (+ a small vendor lib) Split further only with a measurement showing the win
Where a <head> preload or third-party tag goes HtmlPageItemsConfig under /conf Hardcoding it in a page component makes it undeployable by site owners

2. Client libraries

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="cq:ClientLibraryFolder" allowProxy="{Boolean}true"
    categories="[acme.site]" embed="[acme.components.hero,acme.components.teaser]"/>
  • allowProxy="{Boolean}true" on every library under /apps: publish denies reads on /apps, so the library is served from /etc.clientlibs/…. Reference fonts and images relative to the clientlib, never with an /apps/ path — that is why fonts 404 on publish and work on author.
  • Component libraries are embedded into the site library. Including them per component from HTL produces duplicate render-blocking requests and unstable ordering.
  • Include once, from the page component or the Core Page policy, using the Core Components clientlib template (it supports defer; the old Granite template does not).
  • Cloud Service serves content-hashed, long-cache clientlib URLs out of the box. On 6.5 you add a versioned-clientlib solution and the matching dispatcher cache headers.
  • Author-only code (dialog validators, editor extensions) belongs in cq.authoring.dialog or a component's extraClientlibs — never in the site bundle.
  • clientlib.config.js, the frontend-maven-plugin wiring with pinned Node, HtmlPageItemsConfig, ES modules and CSP notes are in references/clientlibs.md.

3. CSS, tokens and the grid

  • Core Components emit BEM (.cmp-teaser, .cmp-teaser__title). Follow the same scheme, one SCSS partial per component.
  • Style System classes land on the component wrapper, not the inner cmp- element:
.cmp-teaser--dark .cmp-teaser__title { color: var(--color-text-inverse); }
  • Design tokens as CSS custom properties. Brands, themes and prefers-color-scheme swap token values, not selectors — a dark mode built from a second set of selectors doubles every future change.
  • Never depend on another component's markup order, on author-only wrappers, or on !important to beat Core CSS. Raise specificity with the block class.
  • The Layout Container's cq:responsive breakpoints and the generated grid SCSS must carry the same widths, or layout mode shows authors a layout visitors never get. The XML and SCSS contract is in references/clientlibs.md.

4. JavaScript that respects the editor

The page editor replaces a component's DOM after every dialog save, so a single DOMContentLoaded pass leaves the component dead until a reload. Initialise idempotently from markup, and re-scan on mutation — the pattern Core Components use:

const SEL = '[data-cmp-is="hero"]';
const init = el => { if (el.dataset.cmpInit) return; el.dataset.cmpInit = 'true'; /* wire up */ };
const scan = node => { if (node.nodeType === 1) { if (node.matches(SEL)) init(node);
                       node.querySelectorAll(SEL).forEach(init); } };
document.addEventListener('DOMContentLoaded', () => {
  scan(document.body);
  new MutationObserver(ms => ms.forEach(m => m.addedNodes.forEach(scan)))
    .observe(document.body, { childList: true, subtree: true });
});
  • Read configuration from data-* attributes; no server values baked into inline scripts.
  • Disable behaviour that fights authors in edit mode — autoplay, scroll hijacking, modals on load, preventDefault on links. Emit a flag from HTL (data-wcmmode="${wcmmode.edit ? 'edit' : ''}" on <body>) instead of sniffing the URL or window.Granite.
  • Test with ?wcmmode=disabled on author and on publish; author adds wrappers and CSS that hide real bugs.
  • Analytics goes through the tag manager and a documented data-layer contract (adobeDataLayer events with named schemas), not hand-rolled vendor snippets in components.

5. Universal Editor and the front-end pipeline

  • Universal Editor on a Sites project needs little front-end work: current Core Components emit the data-aue-* instrumentation themselves, so an HTL page opens in the editor. Custom components emit the attributes themselves — see aem-universal-editor. A SPA is not required and SPA Editor is not an option for new work.
  • Front-end pipeline: a plain Node module whose npm run build produces a dist folder; Cloud Manager deploys the contents of dist as static files, and the site loads them through HtmlPageItemsConfig. A theme that deploys and changes nothing is almost always a missing HtmlPageItemsConfig entry. Full contract and the Site Theme workflow: references/front-end-pipeline.md.

6. Performance and accessibility

  • Images: Core Image v3 with widths configured in the policy so it emits srcset, plus web-optimized image delivery (or Dynamic Media where licensed). Never serve original DAM binaries or hand-built rendition paths. The LCP image loads eagerly with explicit dimensions; everything else lazily.
  • Fonts: self-host in clientlib resources, subset, font-display: swap, preload the one or two critical faces via HtmlPageItemsConfig.
  • Audit the tag manager payload — on most AEM sites it is the largest script and the main contributor to blocking time.
  • Measure on publish behind the CDN with field data (CrUX/RUM) alongside Lighthouse; author-mode numbers are meaningless.
  • Accessibility: visible focus styles, contrast checked for every Style System variant, prefers-reduced-motion, keyboard support for custom widgets, and no display:none on content screen readers need. Run axe against publish-mode renders, including the Core Components library pages.

7. Deliverable format

## Sources — SCSS/JS under ui.frontend (or the theme repo)
## Clientlib — clientlib.config.js / .content.xml changes: category, embed, allowProxy
## Include — HTL or HtmlPageItemsConfig change, with defer/async stated
## Policy — Style System group, label and class; Core Image widths if touched
## Verification — author edit mode, publish, each breakpoint, Lighthouse + axe result

Checklist

  • allowProxy set; no /apps/ URL in any CSS or JS
  • Component libraries embedded in the site library, not included per component
  • Scripts deferred; async only where ordering genuinely does not matter
  • JavaScript re-initialises after an author edit and is idempotent
  • Nothing autoplays, hijacks scroll or blocks clicks in edit mode
  • Style variants are Style System classes on the wrapper, no !important
  • cq:responsive breakpoints match the generated grid SCSS
  • LCP image is eager with dimensions; the rest lazy; srcset comes from the policy
  • Author-only code is not in the publish bundle
  • Generated clientlib folders are not hand-edited
  • Measured on publish behind the CDN, with axe run on the changed components

Anti-patterns

  • Hand-editing generated clientlib folders → change the source and rebuild; they are build output.
  • Missing allowProxy or an /apps/… URL in CSS → allowProxy="{Boolean}true" and clientlib-relative resource paths.
  • A clientlib include per component in HTL → embed the category into the site library.
  • async on libraries that depend on each other → defer, which preserves order.
  • JS that initialises once on load → idempotent init plus a MutationObserver re-scan.
  • Autoplay carousels and modals active in edit mode → gate them on a WCMMode flag emitted from HTL.
  • A new component for a colour variant → a Style System style group.
  • Grid breakpoints that differ from cq:responsive → one source of truth; layout mode must not lie to authors.
  • Serving original DAM binaries, or lazy-loading the hero → policy-driven srcset and eager LCP.
  • A pipeline theme plus a clientlib copy of the same CSS → pick one owner for the file.
  • Measuring performance on author → publish, behind the CDN, with field data.

Go deeper

  • references/clientlibs.md — clientlib.config.js, Maven/npm wiring, clientlib node properties, include templates, HtmlPageItemsConfig, ES modules and CSP, the grid breakpoint contract.
  • references/front-end-pipeline.md — front-end pipeline contract (npm run build → dist → HtmlPageItemsConfig), Site Themes, converting an archetype project, local development.
  • delivery-models.md in ../../architecture/aem-architecture/references/ — which model this front end belongs to.
  • Sibling skills: aem-component-development for HTL and dialogs, aem-universal-editor for in-place editing, aem-performance when a page is slow, aem-edge-delivery-services for EDS block development, aem-code-review for reviews.

References

Deeper material the agent loads only when needed.