Org Skills

aem-dispatcher

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill aem-dispatcher
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill aem-dispatcher -g

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.

Skill contents

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.

References

Deeper material the agent loads only when needed.