Org Skills

aem-edge-delivery-services

Builds sites on AEM Edge Delivery Services (aem.live) — boilerplate setup, content sources (Google Drive, SharePoint, Document Authoring, AEM with the Universal Editor), blocks, the eager/lazy/delayed loading phases, spreadsheets and query-index, preview and publish, RUM and experimentation, with a 100 PageSpeed score as the bar.

Download .zip Raw Source
When agents use itUse this whenever the user works in an aem-boilerplate or aem-boilerplate-xwalk repo, writes or debugs a block (blocks/<name>/<name>.js with export default decorate(block)), edits scripts.js, delayed.js, styles.css, head.html, fstab.yaml or paths.json, configures mountpoints or the configuration service, runs `aem up`, uses .aem.page or .aem.live branch URLs, builds query-index, redirects or placeholders sheets, adds a tag manager or third-party script, fights an LCP or PageSpeed failure on a PR, or asks whether EDS fits versus traditional AEM Sites. Also apply it when someone wants to add React, a bundler or an npm build to an EDS project.

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

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

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

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

Installs into Cursor's skills folder.

npx skills add AGCO-Global/org-skills --skill aem-edge-delivery-services -a cursor

Installs into Gemini CLI's skills folder.

npx skills add AGCO-Global/org-skills --skill aem-edge-delivery-services -a gemini-cli

Nothing to install. Press Download .zip above, unzip it, and drop the aem-edge-delivery-services 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 Edge Delivery Services

Targets: AEM Edge Delivery Services (aem.live) with aem-boilerplate and aem-boilerplate-xwalk · Verified: 2026-09 against https://www.aem.live/developer/keeping-it-100

Edge Delivery is a no-build, no-framework platform: content is authored as documents or in the Universal Editor, turned into semantic HTML at the edge, and decorated by small vanilla JS and CSS blocks that load in strict phases. Judge every decision by two questions — does it keep the page at 100 on mobile PageSpeed, and can an author create it without a developer?

1. Decide first

Question Default Change when
Is EDS right for this site Yes for a marketing or content site where performance and time to launch dominate Auth-gated content, server-side forms, MSM rollouts across many markets, or an app-like UI → see the "wrong answer" list in references/project-setup.md
Content source Document authoring (Drive, SharePoint or da.live) Authors need AEM governance, structured components or translation → AEM with the Universal Editor, on the aem-boilerplate-xwalk template
Where a site setting lives The configuration service It overrides fstab.yaml and .helix/config.xlsx — editing those on a config-service site does nothing
New behaviour A block A content pattern authors should not have to mark up → auto-blocking in scripts.js
Block variant A class in the block name (Cards (compact)) Never a second block
Where a third-party script goes scripts/delayed.js Nowhere else — and not before 3 s after LCP
Data for a list or a label A spreadsheet served as JSON, or placeholders.json Never hard-coded in the block's JavaScript
Build tooling None. ES modules ship as written Adding a bundler, React or an npm runtime dependency is the decision to stop using the platform

2. Project setup

  • Start from the aem-boilerplate GitHub template, or adobe-rnd/aem-boilerplate-xwalk when authors work in AEM through the Universal Editor. Install the AEM Code Sync GitHub app; it syncs code to the edge on every push.
  • Document projects declare the content source in fstab.yaml; current projects use the configuration service, which also enables "repoless" setups — many sites, one code repository.
  • xwalk projects additionally have fstab.yaml pointing at the AEM author service, paths.json mapping author paths to site URLs, and a per-block model JSON that the build merges into component-models.json, component-definition.json and component-filters.json. A block with no model JSON does not appear in the editor.
  • https://<branch>--<repo>--<owner>.aem.page is preview and .aem.live is live; branch names become hostnames, so keep them short and lowercase. Authors preview and publish with the Sidekick.
  • Full setup, the Admin API, sheets, head.html, 404.html, placeholders.json, metadata.xlsx, sitemaps and CDN options: references/project-setup.md.

3. Content modelling for authors

  • A document becomes sections (split by ---), each holding default content (headings, paragraphs, lists, images, links) and blocks (a table whose first cell is the block name).
  • A Section Metadata table sets section classes and data; a Metadata table at the end of the document sets <meta> values read with getMetadata. metadata.xlsx sets them in bulk by path.
  • Options in the block name become classes: Columns (wide, dark) → <div class="columns wide dark">.
  • Prefer default content over blocks. Few rows, few columns, no invisible magic cells, plain-language names. If a block needs a manual to author, redesign the block.
  • Reuse content with fragments (a fragment block pointing at /fragments/…); the header and footer are fragments from /nav and /footer.

4. Blocks

import { createOptimizedPicture } from '../../scripts/aem.js';

export default function decorate(block) {
  const ul = document.createElement('ul');
  [...block.children].forEach((row) => { /* move the author's cells into the new structure */ });
  block.replaceChildren(ul);
}
  • Decorate the DOM the author produced. A block that ignores block.children and rebuilds from hard-coded strings has taken control away from the author.
  • Use the helpers in scripts/aem.js and never edit that file — it tracks upstream, and a local edit turns every boilerplate update into a merge conflict. Project logic belongs in scripts/scripts.js.
  • CSS scoped under the block class, mobile-first, using the custom properties from styles/styles.css. No global resets inside a block.
  • Full block anatomy, the helper list, auto-blocking and @web/test-runner block tests: references/blocks-and-phases.md.

5. Loading phases and the performance bar

Phase What belongs there
Eager (loadEager) Decorating the page and the first section, so the LCP element renders. No third party, no second origin
Lazy (loadLazy) Remaining sections and blocks, header and footer, lazy-styles.css, fonts
Delayed (scripts/delayed.js) Analytics, tag managers, chat, consent, pixels — everything third-party
  • The delayed phase should not start until at least three seconds after the LCP event, and the boilerplate no longer hard-codes that timer. A project that copies the boilerplate and adds a tag manager without setting the delay is loading it immediately; check your loadDelayed rather than assuming.
  • Protect LCP: do not lazy-load the first image, do not insert content above the fold after load, reserve space to avoid CLS, and keep the pre-LCP payload near 100 KB.
  • Field data comes from the built-in RUM sampling (sampleRUM), not from a second analytics library. Personalisation and A/B tests run through the experimentation plugin, driven by page metadata, so the variant is decided at the edge instead of after load.

6. Deliverable format (block spec)

## Block name and purpose — variants as class options
## Authoring table — the rows and columns an author fills, with a filled example and what is optional
## Resulting DOM — after decoration, plus the responsive behaviour
## Data — sheets, query-index or placeholders used, with field names
## Performance — loading phase, LCP impact, images, any third-party dependency
## Test URLs — branch preview before/after, lint result, PageSpeed score

Checklist

  • The block decorates author content rather than replacing it
  • Variants are classes on one block, not extra blocks
  • scripts/aem.js is untouched; project logic is in scripts/scripts.js
  • CSS is scoped to the block class and leaks nothing globally
  • Every third-party script is in the delayed phase, at least 3 s after LCP
  • No second origin is contacted before LCP
  • The first image is not lazy-loaded and space is reserved for it
  • Lists, labels and configuration come from sheets or placeholders.json
  • On xwalk projects, the block has its model JSON and appears in the editor
  • The authoring table is simple enough to use without a manual
  • Branch preview URLs and the PageSpeed result are in the PR

Anti-patterns

  • Adding React, a bundler, TypeScript compilation or npm runtime dependencies → that is a decision to leave the platform; make it explicitly or not at all.
  • Editing scripts/aem.js → put the logic in scripts/scripts.js; the shared library must stay updatable.
  • A tag manager in head.html or the eager phase → delayed.js, after the 3-second rule, with the consent story sorted out.
  • Assuming the boilerplate delays the delayed phase for you → it no longer hard-codes the timer; check loadDelayed.
  • A font or script from another origin before LCP → self-host it or move it later; a new origin costs DNS, TLS and a connection.
  • One huge multi-purpose block → several small ones, or default content.
  • Author-hostile tables (nested tables, positional magic, JSON in a cell) → redesign the authoring model.
  • Copy or a list hard-coded in JavaScript → a sheet, so an author can change it.
  • A custom personalisation library loaded early → the experimentation plugin, at the edge.
  • Merging without branch test URLs or with a PageSpeed regression → the score is the product requirement, not a nice-to-have.

Go deeper

  • references/blocks-and-phases.md — block anatomy and helpers, the three phases in detail, the LCP rules, RUM and experimentation, testing blocks with @web/test-runner.
  • references/project-setup.md — content sources including da.live, the xwalk/Universal Editor project, the configuration service, Admin API, sheets and site files, CDN options, and when EDS is the wrong answer.
  • delivery-models.md in ../../architecture/aem-architecture/references/ — EDS against the other delivery models.
  • Sibling skills: aem-universal-editor for the editing layer on xwalk projects, aem-headless when content also feeds an app, aem-architecture for the platform decision.

References

Deeper material the agent loads only when needed.