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.
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.
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.
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.
---
name: aem-edge-delivery-services
description: >
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. Use 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.
metadata:
technology: AEM
type: development
---
# 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
```js
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.