When agents use itUse this whenever the user edits dispatcher .any, .farm, .vhost, .rules or .vars files (filters.any, rules.any, clientheaders.any, virtualhosts.any, rewrite.rules, global.vars), runs validate.sh or docker_run.sh from the dispatcher SDK, asks why a page is not cached or not invalidated, sees a 404 or a permanent MISS from dispatcher, exposes .json or .model.json, needs a GraphQL or servlet endpoint allowed, wants to purge the CDN or add a Surrogate-Key, configures redirects, CORS or security headers, or edits cdn.yaml. Also apply it when a security or hit-ratio problem on AEM publish turns out to be a filter or cache rule.
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-dispatcher -a github-copilot
# or with the org installer (adds .github/skills/aem-dispatcher):
npx -y github:AGCO-Global/org-skills add skill aem-dispatcher
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-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-dispatcher -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-dispatcher -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-dispatcher -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-dispatcher -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-dispatcher 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.
Dispatcher is both the security perimeter and the cache for AEM publish. Every rule answers two questions: can someone reach something they should not through this? and will this response be cached and correctly invalidated? Deny by default, cache by default, and prove both — with validate.sh, with negative test URLs, and with response headers.
/url only for a prefix-anchored servlet endpoint that selectors cannot express, e.g. /url "/graphql/execute.json*" — Adobe's own default rule
Starting point for filters
The inherited deny-all in default_filters.any, extended with narrow allows
Never a permissive base with denies bolted on
Cacheability of a new endpoint
Cacheable: GET, no cookies, no auth header, stable URL
Genuinely per-user → mark it uncacheable and keep it off the HTML path
Query parameters
Ignore everything (/glob "*" /type "allow"), deny the few that change the response
A parameter that selects content must be deny-listed, or you serve the wrong page
Getting fresh content out
Automatic invalidation on publish, plus TTLs
Unpredictable events (hotfix, emergency copy) → CDN purge by URL or Surrogate-Key
Redirect location
cdn.yamlredirects for marketer-owned lists; rewrite.rules for a small stable set
A redirect that depends on publish state belongs in AEM, not the edge
Authenticated content
Keep it out of the cache (/allowAuthorized "0", the default)
Large secured site → permission-sensitive caching with auth_checker, deliberately
Where CDN rules live
config/cdn.yaml on a config pipeline
Nothing CDN-related belongs in the full-stack pipeline
File layout, the immutable-file list, global.vars flags and the SDK commands are in references/flexible-mode-layout.md. Run ./bin/validate.sh ./src before every commit — it is the same check the web-tier pipeline runs.
2. Filters: allow-list only
Filters are evaluated top to bottom and last match wins. Extend the inherited deny-all; do not restate it.
Structured matchers exist because a /url glob is bypassable with an extra selector or suffix. The documented exception is a servlet endpoint whose URL carries a ;var=value suffix that /path + /extension cannot express — Adobe's own GraphQL defaults are /url "/content/_cq_graphql/*/endpoint.json" with (POST|OPTIONS) and /url "/graphql/execute.json*" with (GET|POST|OPTIONS). If you write a /url rule, anchor it at a prefix and say in the PR why.
Never allow /crx/*, /system/*, /libs/* or /bin/* broadly. One exact servlet path, with the method, is the most you should ever allow.
.json only with an explicit selector and path; deny numeric selectors (.1.json, .-1.json) so recursive JSON rendering cannot dump a tree.
POST only to exact form-handler paths. A filter change is not finished until every blocked URL in your negative-test list returns 404.
3. Cache rules and invalidation
/rules: cache * under content paths; deny only what must never be cached.
/ignoreUrlParams decides your hit ratio. Ignore everything, then deny the parameters that select content — otherwise every utm_* and gclid is a cache miss:
/ignoreUrlParams {
/0001 { /glob "*" /type "allow" } # allow = ignore when caching
/0002 { /glob "page" /type "deny" } # deny = the response depends on it
}
/statfileslevel is the invalidation blast radius: set it to the depth of your site roots (/content/brand/country/lang → 4 or 5). Too low invalidates every site on one publish; too high leaves shared headers and footers stale.
/invalidate auto-invalidates *.html and page .json on activation. Do not auto-invalidate clientlibs or DAM renditions — they carry fingerprinted URLs.
/enableTTL "1" makes dispatcher honour Cache-Control: max-age from publish; use it for API-style responses that should expire rather than wait for an invalidation.
Caching persisted GraphQL queries additionally requires CACHE_GRAPHQL_PERSISTED_QUERIES in conf.d/variables/global.vars. Without it the rules above are irrelevant and every query reaches publish.
On Cloud Service invalidation happens automatically through content distribution; on 6.5 it comes from flush agents on publish calling /dispatcher/invalidate.cache — a flush agent configured on author instead of publish is the classic 6.5 bug.
4. CDN: purge, traffic filters, BYO
Purge by URL or by Surrogate-Key with a PURGE request carrying X-AEM-Purge-Key, and X-AEM-Purge: soft (revalidate, keep serving) or hard (evict now, the default). The key is declared as a purge authenticator in cdn.yaml from a Cloud Manager secret variable.
Traffic filter and WAF rules, redirects, request/response transformations and origin selectors all live in config/cdn.yaml (kind: "CDN", version: "1") on a config pipeline, capped at 100 KB across all config files. Ship every new filter rule in log action first, read the CDN logs, then switch to block.
Full syntax, the purge YAML, surrogate-key design and BYO CDN headers: references/cdn-config.md.
5. Rewrites, redirects, headers and CORS
Short URLs: mod_rewrite[PT] rules plus Sling mappings, so links are also written short. Keep chains to one hop, always use L, and verify with curl -I.
Vanity URLs (sling:vanityPath) need the dispatcher /vanity_urls feature enabled and its endpoint allowed; otherwise every unknown URL falls through to publish.
Security headers belong in the vhost: Strict-Transport-Security, X-Content-Type-Options: nosniff, CSP frame-ancestors, Referrer-Policy. Set Cache-Control per path pattern (short for HTML, long + immutable for fingerprinted clientlibs); Surrogate-Control targets the CDN only.
CORS is an AEM concern, not an Apache one: configure com.adobe.granite.cors.impl.CORSPolicyImpl~<name> with alloworigin, alloworiginregexp, allowedpaths, supportedmethods, supportedheaders, supportscredentials, exposedheaders, maxage:Integer — and pass Origin plus Access-Control-Request-* through clientheaders.any, or the request never reaches the policy.
Permission-sensitive caching: /allowAuthorized "1" plus an /auth_checker block naming a permission-check servlet, a /filter list of the secured paths and a /headers list. /auth_checker is a top-level dispatcher directive — the SDK validator rejects it when it is nested inside a .farm entry, so validate before you deploy. Without it, /allowAuthorized "1" serves one user's page to everyone.
6. Debugging
Local: X-Dispatcher-Info: true on the request makes the SDK container explain its cache and filter decision; DISP_LOG_LEVEL=trace1 puts it in dispatcher.log.
Cloud: x-cache and age response headers, plus dispatcher and CDN logs from Cloud Manager.
404 with a healthy publish = a filter denied it. 200 but always MISS = an auth header or cookie, an un-ignored query parameter, Cache-Control: private, or a /rules deny. Stale after publish = statfileslevel or a shared fragment.
Deliverable format
| URL / pattern | Expected | Actual (filter · cache · TTL) | Risk | Fix |
|---|---|---|---|---|
| /content/acme/en.model.json | 200, cached 5 min | allowed, never cached (utm_* param) | Hit ratio 40 % | Ignore `*` in /ignoreUrlParams, deny only `page` |
| /content/acme/en.infinity.json | 404 | 200 | Content structure leak | Deny the `infinity` selector |
Close with: the corrected snippets, validate.sh output, the negative-test URL list, and the expected hit-ratio impact.
Checklist
validate.sh passes and no default_* or immutable file was edited
Filters extend the inherited deny-all; every allow is structured, or a /url prefix with a stated reason
/crx, /system/console, .infinity.json, Query Builder and numeric-selector JSON return 404 on publish
/ignoreUrlParams ignores everything except the parameters that select content
/statfileslevel matches the site-root depth; shared fragments have an invalidation story
Persisted GraphQL caching has CACHE_GRAPHQL_PERSISTED_QUERIES set
/allowAuthorized is 0, or auth_checker is configured and validated
CORS policy lists allowedpaths and named origins, and clientheaders.any passes Origin
CDN rules are in config/cdn.yaml on a config pipeline, new filters in log mode first
A purge path exists (key configured, surrogate keys emitted) for content that cannot wait for a TTL
enabled_vhosts / enabled_farms entries are real relative symlinks
Anti-patterns
Allow-all filters with a handful of denies → start from the inherited deny-all and add narrow allows.
/url "/bin/*" to expose a servlet → bind the servlet to a resource type with a selector and allow that, or allow one exact path with the method.
Editing default_filters.any or dispatcher.any → $include them from your own file; the pipeline rejects edits.
/statfileslevel "0" on a multi-site estate → set it to the site-root depth; otherwise one publish flushes everything.
Caching every query-string variant → ignore * and deny the few that matter.
/allowAuthorized "1" with no auth_checker → turn it back off until permission-sensitive caching is configured and tested.
Long HTML TTLs with no purge path → configure a purge key and surrogate keys, then keep the TTL.
Access-Control-Allow-Origin: * on a cached response → an explicit origin list in CORSPolicyImpl, and vary the cache per origin.
"Fix it by lowering the TTL" → find the reason for the MISS first; a low TTL hides a broken invalidation until traffic doubles.
Sibling skills: aem-performance when the symptom is slowness rather than a rule, aem-headless for the GraphQL contract, aem-security for WAF, CUGs and secrets, aem-cloud-manager for the config pipeline, aem-code-review for reviews.
---
name: aem-dispatcher
description: >
Writes and debugs AEM Dispatcher and Adobe CDN configuration — flexible-mode file layout, deny-by-default filters, cache rules, ignoreUrlParams and statfileslevel, invalidation and CDN purge, TTLs and ETags, rewrites, redirects and vanity URLs, security headers, CORS, permission-sensitive caching, and cdn.yaml traffic filters and WAF. Use this whenever the user edits dispatcher .any, .farm, .vhost, .rules or .vars files (filters.any, rules.any, clientheaders.any, virtualhosts.any, rewrite.rules, global.vars), runs validate.sh or docker_run.sh from the dispatcher SDK, asks why a page is not cached or not invalidated, sees a 404 or a permanent MISS from dispatcher, exposes .json or .model.json, needs a GraphQL or servlet endpoint allowed, wants to purge the CDN or add a Surrogate-Key, configures redirects, CORS or security headers, or edits cdn.yaml. Also apply it when a security or hit-ratio problem on AEM publish turns out to be a filter or cache rule.
metadata:
technology: AEM
type: architecture
---
# AEM Dispatcher and CDN
> **Targets:** AEM as a Cloud Service (dispatcher SDK, flexible mode) and the Adobe-managed CDN; AEM 6.5 noted where different · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/dispatcher/disp-overview
Dispatcher is both the security perimeter and the cache for AEM publish. Every rule answers two questions: *can someone reach something they should not through this?* and *will this response be cached and correctly invalidated?* Deny by default, cache by default, and prove both — with `validate.sh`, with negative test URLs, and with response headers.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Filter matcher | Structured: `/path` + `/selectors` + `/extension` + `/method` | `/url` only for a prefix-anchored servlet endpoint that selectors cannot express, e.g. `/url "/graphql/execute.json*"` — Adobe's own default rule |
| Starting point for filters | The inherited deny-all in `default_filters.any`, extended with narrow allows | Never a permissive base with denies bolted on |
| Cacheability of a new endpoint | Cacheable: GET, no cookies, no auth header, stable URL | Genuinely per-user → mark it uncacheable and keep it off the HTML path |
| Query parameters | Ignore everything (`/glob "*" /type "allow"`), deny the few that change the response | A parameter that selects content must be `deny`-listed, or you serve the wrong page |
| Getting fresh content out | Automatic invalidation on publish, plus TTLs | Unpredictable events (hotfix, emergency copy) → CDN purge by URL or `Surrogate-Key` |
| Redirect location | `cdn.yaml` `redirects` for marketer-owned lists; `rewrite.rules` for a small stable set | A redirect that depends on publish state belongs in AEM, not the edge |
| Authenticated content | Keep it out of the cache (`/allowAuthorized "0"`, the default) | Large secured site → permission-sensitive caching with `auth_checker`, deliberately |
| Where CDN rules live | `config/cdn.yaml` on a config pipeline | Nothing CDN-related belongs in the full-stack pipeline |
File layout, the immutable-file list, `global.vars` flags and the SDK commands are in `references/flexible-mode-layout.md`. Run `./bin/validate.sh ./src` before every commit — it is the same check the web-tier pipeline runs.
## 2. Filters: allow-list only
Filters are evaluated top to bottom and **last match wins**. Extend the inherited deny-all; do not restate it.
```
/filters {
$include "../filters/default_filters.any"
/0100 { /type "allow" /method "GET" /path "/content/acme/*" /extension "html" }
/0101 { /type "allow" /method "GET" /path "/content/acme/*" /selectors "model" /extension "json" }
/0110 { /type "deny" /selectors '(feed|rss|pages|languages|blueprint|infinity|tidy|sysview|docview|query|[0-9-]+)' /extension "json" }
/0111 { /type "deny" /path "/content/*" /query "debug=*" }
}
```
- Structured matchers exist because a `/url` glob is bypassable with an extra selector or suffix. The documented exception is a servlet endpoint whose URL carries a `;var=value` suffix that `/path` + `/extension` cannot express — Adobe's own GraphQL defaults are `/url "/content/_cq_graphql/*/endpoint.json"` with `(POST|OPTIONS)` and `/url "/graphql/execute.json*"` with `(GET|POST|OPTIONS)`. If you write a `/url` rule, anchor it at a prefix and say in the PR why.
- Never allow `/crx/*`, `/system/*`, `/libs/*` or `/bin/*` broadly. One exact servlet path, with the method, is the most you should ever allow.
- `.json` only with an explicit selector and path; deny numeric selectors (`.1.json`, `.-1.json`) so recursive JSON rendering cannot dump a tree.
- POST only to exact form-handler paths. A filter change is not finished until every blocked URL in your negative-test list returns 404.
## 3. Cache rules and invalidation
- `/rules`: cache `*` under content paths; deny only what must never be cached.
- **`/ignoreUrlParams`** decides your hit ratio. Ignore everything, then deny the parameters that select content — otherwise every `utm_*` and `gclid` is a cache miss:
```
/ignoreUrlParams {
/0001 { /glob "*" /type "allow" } # allow = ignore when caching
/0002 { /glob "page" /type "deny" } # deny = the response depends on it
}
```
- **`/statfileslevel`** is the invalidation blast radius: set it to the depth of your site roots (`/content/brand/country/lang` → 4 or 5). Too low invalidates every site on one publish; too high leaves shared headers and footers stale.
- **`/invalidate`** auto-invalidates `*.html` and page `.json` on activation. Do not auto-invalidate clientlibs or DAM renditions — they carry fingerprinted URLs.
- **`/enableTTL "1"`** makes dispatcher honour `Cache-Control: max-age` from publish; use it for API-style responses that should expire rather than wait for an invalidation.
- Caching persisted GraphQL queries additionally requires `CACHE_GRAPHQL_PERSISTED_QUERIES` in `conf.d/variables/global.vars`. Without it the rules above are irrelevant and every query reaches publish.
- On Cloud Service invalidation happens automatically through content distribution; on 6.5 it comes from flush agents on publish calling `/dispatcher/invalidate.cache` — a flush agent configured on author instead of publish is the classic 6.5 bug.
## 4. CDN: purge, traffic filters, BYO
- Purge by URL or by `Surrogate-Key` with a `PURGE` request carrying `X-AEM-Purge-Key`, and `X-AEM-Purge: soft` (revalidate, keep serving) or `hard` (evict now, the default). The key is declared as a `purge` authenticator in `cdn.yaml` from a Cloud Manager secret variable.
- Traffic filter and WAF rules, redirects, request/response transformations and origin selectors all live in `config/cdn.yaml` (`kind: "CDN"`, `version: "1"`) on a config pipeline, capped at 100 KB across all config files. Ship every new filter rule in `log` action first, read the CDN logs, then switch to `block`.
- Full syntax, the purge YAML, surrogate-key design and BYO CDN headers: `references/cdn-config.md`.
## 5. Rewrites, redirects, headers and CORS
- Short URLs: `mod_rewrite` `[PT]` rules plus Sling mappings, so links are also *written* short. Keep chains to one hop, always use `L`, and verify with `curl -I`.
- Vanity URLs (`sling:vanityPath`) need the dispatcher `/vanity_urls` feature enabled and its endpoint allowed; otherwise every unknown URL falls through to publish.
- Security headers belong in the vhost: `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`, CSP `frame-ancestors`, `Referrer-Policy`. Set `Cache-Control` per path pattern (short for HTML, long + `immutable` for fingerprinted clientlibs); `Surrogate-Control` targets the CDN only.
- **CORS** is an AEM concern, not an Apache one: configure `com.adobe.granite.cors.impl.CORSPolicyImpl~<name>` with `alloworigin`, `alloworiginregexp`, `allowedpaths`, `supportedmethods`, `supportedheaders`, `supportscredentials`, `exposedheaders`, `maxage:Integer` — and pass `Origin` plus `Access-Control-Request-*` through `clientheaders.any`, or the request never reaches the policy.
- **Permission-sensitive caching**: `/allowAuthorized "1"` plus an `/auth_checker` block naming a permission-check servlet, a `/filter` list of the secured paths and a `/headers` list. `/auth_checker` is a top-level dispatcher directive — the SDK validator rejects it when it is nested inside a `.farm` entry, so validate before you deploy. Without it, `/allowAuthorized "1"` serves one user's page to everyone.
## 6. Debugging
- Local: `X-Dispatcher-Info: true` on the request makes the SDK container explain its cache and filter decision; `DISP_LOG_LEVEL=trace1` puts it in `dispatcher.log`.
- Cloud: `x-cache` and `age` response headers, plus dispatcher and CDN logs from Cloud Manager.
- **404 with a healthy publish** = a filter denied it. **200 but always MISS** = an auth header or cookie, an un-ignored query parameter, `Cache-Control: private`, or a `/rules` deny. **Stale after publish** = statfileslevel or a shared fragment.
## Deliverable format
```
| URL / pattern | Expected | Actual (filter · cache · TTL) | Risk | Fix |
|---|---|---|---|---|
| /content/acme/en.model.json | 200, cached 5 min | allowed, never cached (utm_* param) | Hit ratio 40 % | Ignore `*` in /ignoreUrlParams, deny only `page` |
| /content/acme/en.infinity.json | 404 | 200 | Content structure leak | Deny the `infinity` selector |
```
Close with: the corrected snippets, `validate.sh` output, the negative-test URL list, and the expected hit-ratio impact.
## Checklist
- [ ] `validate.sh` passes and no `default_*` or immutable file was edited
- [ ] Filters extend the inherited deny-all; every allow is structured, or a `/url` prefix with a stated reason
- [ ] `/crx`, `/system/console`, `.infinity.json`, Query Builder and numeric-selector JSON return 404 on publish
- [ ] `/ignoreUrlParams` ignores everything except the parameters that select content
- [ ] `/statfileslevel` matches the site-root depth; shared fragments have an invalidation story
- [ ] Persisted GraphQL caching has `CACHE_GRAPHQL_PERSISTED_QUERIES` set
- [ ] `/allowAuthorized` is `0`, or `auth_checker` is configured and validated
- [ ] CORS policy lists `allowedpaths` and named origins, and `clientheaders.any` passes `Origin`
- [ ] CDN rules are in `config/cdn.yaml` on a config pipeline, new filters in `log` mode first
- [ ] A purge path exists (key configured, surrogate keys emitted) for content that cannot wait for a TTL
- [ ] `enabled_vhosts` / `enabled_farms` entries are real relative symlinks
## Anti-patterns
- **Allow-all filters with a handful of denies** → start from the inherited deny-all and add narrow allows.
- **`/url "/bin/*"` to expose a servlet** → bind the servlet to a resource type with a selector and allow that, or allow one exact path with the method.
- **Editing `default_filters.any` or `dispatcher.any`** → `$include` them from your own file; the pipeline rejects edits.
- **`/statfileslevel "0"` on a multi-site estate** → set it to the site-root depth; otherwise one publish flushes everything.
- **Caching every query-string variant** → ignore `*` and deny the few that matter.
- **`/allowAuthorized "1"` with no `auth_checker`** → turn it back off until permission-sensitive caching is configured and tested.
- **Long HTML TTLs with no purge path** → configure a purge key and surrogate keys, then keep the TTL.
- **`Access-Control-Allow-Origin: *` on a cached response** → an explicit origin list in `CORSPolicyImpl`, and vary the cache per origin.
- **"Fix it by lowering the TTL"** → find the reason for the MISS first; a low TTL hides a broken invalidation until traffic doubles.
## Go deeper
- `references/flexible-mode-layout.md` — module layout, immutable files, `global.vars` flags, `validate.sh`/`docker_run.sh`, 6.5 differences.
- `references/cdn-config.md` — `cdn.yaml` shape, config-pipeline kinds, purge authenticator and `PURGE` calls, traffic filters, BYO CDN headers.
- Sibling skills: `aem-performance` when the symptom is slowness rather than a rule, `aem-headless` for the GraphQL contract, `aem-security` for WAF, CUGs and secrets, `aem-cloud-manager` for the config pipeline, `aem-code-review` for reviews.