Org Skills

aem-performance

Diagnoses and fixes Adobe Experience Manager slowness by layer — CDN and dispatcher hit ratio, uncacheable requests, slow JCR queries and missing Oak indexes, heavy Sling Models and HTL, blocking external calls, Sling Dynamic Include, Core Web Vitals, and author-side backlogs.

Download .zip Raw Source
When agents use itUse this whenever the user says AEM pages or the author UI are slow, TTFB or LCP is high, publish CPU spikes under normal traffic, the cache hit ratio is low, error.log shows "Traversed … nodes" or a query limit exception, a Sling Model or HTL render is slow, workflows, Sling Job queues, replication, asset processing or MSM rollouts back up, or they ask about thread dumps, request.log, rlog, the Developer Console, CDN logs or load testing AEM. For a PageSpeed or Lighthouse problem on an Edge Delivery Services site use `aem-edge-delivery-services` instead. Also apply it when apparent capacity trouble turns out to be a caching or query problem.

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

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-performance
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill aem-performance -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-performance -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-performance -a codex

Installs into Cursor's skills folder.

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

Installs into Gemini CLI's skills folder.

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

Nothing to install. Press Download .zip above, unzip it, and drop the aem-performance 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 Performance

Targets: AEM as a Cloud Service 2026.x, AEM 6.5 noted where different · Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/caching

On AEM the fastest request is the one publish never sees. Work down the layers in order — cacheability, then queries, then render code, then the front end — and measure before and after each change with the same tool. Intuition about which layer is slow is wrong often enough that an unmeasured fix is a guess with a deployment attached.

1. Decide first

Question Default Change when
Where to look first Cache hit ratio at the CDN The URL is already a HIT and still slow → go to the render path
Is this a capacity problem? No, until the hit ratio is above ~90 % on anonymous HTML Hit ratio is good, queries are indexed, and publish still saturates
A query is slow It is missing an index — fix the index The query itself is unbounded (p.limit=-1, exact totals) → fix the query first
Personalised fragment on a cached page Client-side fetch The fragment must be server-rendered → Sling Dynamic Include with SSI (mod_include); ESI is not supported on the Adobe CDN
Good TTFB, bad LCP A front-end problem — hero image, fonts, tag manager Never add publish capacity for an LCP number
Author is slow, publish is fine Workflow, job queue, asset or rollout backlog Large Content Fragment or DAM folders → folder structure, not capacity
Measurement source Field data (CrUX/RUM) for CWV, CDN logs for hit ratio Lighthouse alone is a lab signal and will mislead on mobile

2. Triage table

Symptom Likely layer Evidence to collect Owner
High TTFB on anonymous pages CDN/dispatcher miss x-cache, age, CDN log cache field by path aem-dispatcher
Publish CPU high, traffic normal Low hit ratio or over-invalidation Requests reaching publish/s; statfile touches; publish frequency aem-dispatcher
One page type slow even uncached Query or render cost request.log + rlog.jar, Developer Console → Queries §3, §4
Traversed N nodes / query limit exception Missing or wrong index Explain Query plan §3
Slow only when a partner API is slow Blocking outbound call Thread dumps: threads stuck in socket read §5
Good TTFB, poor LCP/CLS Front end Field CWV + waterfall §6
Periodic slowdowns Jobs, GC, workflows GC logs, Sling Job queues, scheduler activity §7
Author sluggish Backlogs Workflow console, job queues, replication queue §7

Cache-rule specifics (/ignoreUrlParams, /statfileslevel, TTLs, purge) belong to aem-dispatcher — collect the evidence here, fix it there.

3. Queries and indexes

  • Every query in production code must hit an index. Run it through Explain Query (Developer Console → Queries on Cloud Service; Tools → Operations → Diagnosis on 6.5). A plan containing /* traverse */, or a different index than you expected, is the finding.
  • Traversed N nodes in error.log and Oak read-limit exceptions are failures, not noise. Cloud Service manages the limits and you cannot raise them — that is the point.
  • Cloud Service supports only type="lucene" definitions, named <prefix>.<name>-<productVersion>-custom-<n> — for example acme.article-1-custom-1. The rule, a complete definition and the packaging settings are in oak-index-naming.md in ../../development/aem-backend-development/references/; do not invent a second convention here.
  • Constrain queries: node type, ISDESCENDANTNODE, p.limit with p.guessTotal=true. p.facets costs an extra pass over the result set — measure before adding facets to a request path.
  • Do not query per render. Precompute on activation, cache in a service with a TTL, or traverse a small known subtree.

4. Sling Models and HTL

  • @Model(adaptables = SlingHttpServletRequest.class, defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL) with @ValueMapValue / @ChildResource. Plain @Inject makes the injector try every strategy in turn — measurable in hot components.
  • Compute once in @PostConstruct; HTL calls a getter every time it appears in the template, including inside loops.
  • Resolve resources once and pass them down. Re-walking getParent() chains or re-adapting in every child component is the most common self-inflicted render cost.
  • No JCR queries, no HTTP calls and no getServiceResourceResolver() inside a component render.
  • Heavy navigation and footers: render as an Experience Fragment or a cached include, not recomputed per page.

5. External calls

  • One OSGi service per integration, with a pooled client, explicit connect and socket timeouts, a fallback, and a TTL cache keyed by the request parameters (aem-backend-development). Without timeouts, a slow partner turns into exhausted request threads and an outage.
  • Refresh on a schedule on author where freshness allows; publish reads the cached copy.
  • Per-user or real-time data is fetched client-side so the page stays cacheable.

6. Front end and dynamic fragments

  • LCP: Core Image v3 with web-optimized image delivery or Dynamic Media (responsive widths, modern formats). Core Image lazy-loads by default — turn lazy loading off for the hero, set width and height, and preload it if the waterfall shows a late discovery.
  • Clientlibs: split per template, defer non-critical JS, fingerprinted long-cache URLs. Audit the tag manager payload; it is usually the largest script on the page.
  • Fonts: self-host, subset, font-display: swap, preload the one or two critical faces.
  • Sling Dynamic Include lets the page stay cached while one component is dynamic. On Cloud Service use SSI — mod_include is enabled on the dispatcher — or a client-side include. ESI is not available at the Adobe CDN, so an SDI configuration that emits ESI silently serves nothing.
  • GraphQL-driven front ends: query cost grows with fragment-reference depth; see aem-headless before blaming the network.

7. Author and background work

  • Workflows: transient where no history is needed; purge completed instances; launchers scoped to a path and a node type, never every change under /content.
  • Sling Jobs: check queue depth and queue.maxparallel before raising concurrency; a saturated queue looks exactly like a slow author.
  • Assets: Cloud Service processes through asset microservices driven by folder processing profiles — keep custom post-processing light and check the Bulk Import backlog before blaming the UI. On 6.5, tune DAM Update Asset.
  • Large folders: keep DAM and Content Fragment folders in the low thousands of children. A flat folder with 100k assets is slow in the UI, in queries and in rollouts.
  • MSM: roll out in batches off-peak; a rollout config triggered on every modification will back up the queue.
  • Reindexing, large package installs and bulk activations are off-peak work.

Deliverable format

## Symptom and baseline — metric, value, tool, URL set, time window
## Findings
| Layer | Evidence | Impact | Fix | Effort |
|---|---|---|---|---|
| CDN | 58 % HIT on /content/acme/*.html; utm_* in cache key | ~4x publish load | Ignore `*` in /ignoreUrlParams, deny only `page` | S |
## Changes — diffs: index definitions, dispatcher rules, model refactors
## Verification — same measurement after the change, hit ratio and CWV delta
## Follow-ups — alerts that would catch the regression

Checklist

  • A baseline number exists, with the tool and the time window that produced it
  • Hit ratio measured per path and content type before any capacity discussion
  • Every query in the changed code has an Explain Query plan attached
  • Index definitions are lucene and correctly named
  • No query, HTTP call or resolver acquisition inside a component render
  • Outbound calls have connect and socket timeouts and a fallback
  • LCP element is not lazy-loaded and has explicit dimensions
  • Dynamic fragments use SSI or client-side include, never ESI
  • Author findings name the queue or folder, not "author is slow"
  • The same measurement is repeated after the fix and reported

Anti-patterns

  • Adding publish capacity before measuring hit ratio → autoscaling multiplies a bad query, it does not fix it.
  • Raising a query limit instead of adding an index → on Cloud Service you cannot, and on 6.5 you are hiding a traversal.
  • Index named mysite-articles-custom-1 or type="property" → acme.articles-1-custom-1, type="lucene".
  • A query inside a Sling Model getter → precompute in @PostConstruct or cache in a service.
  • External HTTP on the request thread with default timeouts → explicit timeouts, cache, fallback.
  • Lazy-loading the hero image → the LCP element loads eagerly, with dimensions.
  • Configuring SDI with ESI on Cloud Service → SSI via mod_include, or a client-side include.
  • Clearing a replication or workflow queue to "fix" it → find the failing item; clearing loses the work and the evidence.
  • Load tests that bypass the CDN → run against stage through the full path, and report the hit ratio the test achieved.

Go deeper

  • references/diagnostics.md — tool-per-question table, CDN log fields and a hit-ratio-per-path recipe, rlog.jar usage, Oak query limits, how to run a load test that means something.
  • oak-index-naming.md in ../../development/aem-backend-development/references/ — index naming, lucene-only rule, a complete definition.
  • Sibling skills: aem-dispatcher for cache and CDN rules, aem-backend-development for query and service code, aem-frontend-development for clientlibs and Core Web Vitals, aem-headless for GraphQL cost, aem-assets for processing and DAM structure.

References

Deeper material the agent loads only when needed.