Reviews AEM code changes — pull requests, diffs or content packages — against a severity-ranked checklist covering security and XSS contexts, resource handling, performance and cacheability, Sling Models, OSGi services, components and dialogs, Cloud Service compatibility, package filters and index names, dispatcher and CDN rules, headless and Universal Editor concerns, tests and accessibility, and returns a findings table with a merge verdict.
When agents use itUse this whenever the user asks to review an AEM PR or diff; pastes HTL, a Sling Model, a servlet, an OSGi service, a .cfg.json, filter.xml, a _cq_dialog, a clientlib or a dispatcher .any file and asks "is this OK"; mentions context='unsafe', ResourceResolverFactory, loginAdministrative, QueryBuilder, @Model, sling.servlet.paths, a SonarQube or Cloud Manager code-quality failure; or wants a pre-merge self-review. Also use it when auditing an inherited AEM codebase.
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-code-review -a github-copilot
# or with the org installer (adds .github/skills/aem-code-review):
npx -y github:AGCO-Global/org-skills add skill aem-code-review
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-quality-skills plugin, which bundles all AEM / Quality skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-quality-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-code-review -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-code-review -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-code-review -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-code-review -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-code-review 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.
AEM bugs hide in the gaps between layers: an HTL context, a leaked resolver, a filter mode, a dispatcher rule. Review each change against the runtime it will actually hit — cached publish, several pods, an immutable /apps — and for every finding cite the line, name the impact, and give the fix. A review that lists problems without fixes moves the work, it does not reduce it.
1. Decide first
Question
Default
Change when
Diff size
Review it all
Over ~400 non-generated lines → ask for a split, or review the riskiest layer in depth and say what you did not review
Where to start
The layer with the highest blast radius: filter.xml, dispatcher, security
A focused PR with one layer — then follow the diff order
Severity of an HTL context
unsafe → blocker; html on RTE output → fine; html on a plain textfield → major
Never wave unsafe through because "the value is ours"
A replace-mode filter on author-owned content
Blocker
Only /apps and /oak:index are safe in replace mode
Generated files (clientlib output, dist)
Do not review their diffs
But do check the source changed too
Cloud Manager was green
Not evidence
The gates miss filter modes, HTL contexts, cache impact and authoring breakage
Verdict
Any blocker, or an untracked major → Request changes
Otherwise Approve, with minor changes if minors exist
2. Before reading the diff
Get the intent in one sentence — the ticket, or ask. A review without intent becomes a style review.
Work out what runs where: author only, publish, both; request time or background; cached or not. Most AEM findings are really "this is fine on author".
List the layers touched — core Java, HTL and dialogs, ui.config, ui.content and filters, dispatcher, ui.frontend, tests — and run the matching sections of references/review-checklist.md.
3. Severity scale
Label
Meaning
Blocks merge?
[blocker]
Security hole, content or data loss, resource leak, Cloud Service incompatibility, outage risk
Yes
[major]
Performance regression, cache-busting, likely bug, missing test for new logic, accessibility failure on a primary flow
Yes, unless deferred with a ticket
[minor]
Maintainability, non-idiomatic AEM usage, small duplication
No
[nit]
Style the tooling does not catch
No
[question]
Intent needed before judging
—
[praise]
Worth copying
—
4. The findings that matter most
The full layer-by-layer checklist is in references/review-checklist.md. These are the ones that appear in almost every AEM review:
Unclosed service resolver → blocker. try (ResourceResolver rr = factory.getServiceResourceResolver(…)); never close the request's resolver; never keep one in a field.
loginAdministrative or an admin session → blocker. Service user from repoinit, one sub-service per concern.
context='unsafe' → blocker. context='html' on a plain textfield → major; on RTE output it is correct.
<filter root="/content/acme"/> with no mode → blocker: replace mode deletes authored content on every deploy.
Path-bound servlet (sling.servlet.paths under /bin) → resource type plus selector, or justify the path and show the dispatcher allow.
A query with no matching index, or an index named mysite-articles-custom-1 instead of acme.articles-1-custom-1 with type="lucene".
A mixed package (/apps plus /content) → fails the gates, and mixes immutable with mutable.
Ad-hoc POST GraphQL, or a token in a browser bundle on a headless front end.
Secrets or hostnames committed in a .cfg.json → $[secret:] / $[env:].
5. Reviewing a diff you cannot run
You will usually be reading text, not a running instance. Ask for the three artefacts that turn a guess into a finding:
The query plan (Explain Query output) for any new or changed query.
The dispatcher validator output, and a curl -I of one affected URL, for any dispatcher or CDN change.
A sample .model.json response for a changed exporter, or the rendered HTML for a changed HTL file.
If they are not available, say which findings are provisional rather than asserting them.
6. Deliverable format
## Findings
| Severity | File:line | Issue | Why it matters | Fix |
|---|---|---|---|---|
| [blocker] | core/…/TeaserModel.java:42 | Service resolver never closed | Leaks sessions until the pod degrades | try-with-resources around getServiceResourceResolver |
| [blocker] | ui.content/…/filter.xml:6 | `/content/acme` filter in replace mode | Deletes authored pages on every deploy | Add mode="merge" and narrow the root |
| [major] | ui.apps/…/teaser.html:18 | `context='html'` on a plain textfield | Stored XSS if the field is not RTE-filtered | Drop the context, or sanitise with XSSAPI.filterHTML |
## Summary
Verdict: Approve | Approve with minor changes | Request changes
Blockers: <n> Majors: <n> Minors: <n>
Top 3 to address: 1. … 2. … 3. …
Not reviewed: <layers or files skipped, and why>
What's good: <genuine, specific praise>
Checklist
Intent understood before the first comment
Every touched layer covered, or the gaps named under "Not reviewed"
Every finding cites a file and line, an impact and a concrete fix
Security, resource handling and filter.xml checked even if the PR is "just a component"
Index names and package types checked whenever ui.apps or ui.content changed
Cacheability considered for anything that changes a response
Tests exist for new logic and regressions for fixed bugs
Accessibility and i18n checked on user-facing markup
Provisional findings marked as provisional
Verdict follows the rule, not the mood of the thread
Anti-patterns
Approving because Cloud Manager passed → the gates do not see filter modes, HTL contexts or cache impact.
Nitpicking Java style while a resolver leaks → severity order, always; report findings highest first.
"Use Core Components" with no proxy path and no reason → name the component, the version and what it replaces.
Skipping the dispatcher and ui.config diffs because they are "not code" → they are the highest-blast-radius files in the repository.
Requesting a rewrite to your own patterns when the repository convention is sound and consistent.
A blocker with no line and no realistic impact → if you cannot show it, mark it as a question.
Reviewing generated clientlib output line by line → check the source instead.
No praise at all → name one thing worth copying; it is how conventions spread.
Go deeper
references/review-checklist.md — the full layer-by-layer checklist: security, resources, performance, Sling Models, OSGi, components and dialogs, Cloud compatibility, packages and indexes, dispatcher, headless and Universal Editor, EDS, tests, accessibility.
oak-index-naming.md in ../../development/aem-backend-development/references/ — the index grammar to check names against.
Sibling skills: the development skills own the rules this checklist enforces (aem-backend-development, aem-component-development, aem-frontend-development, aem-dispatcher, aem-headless, aem-edge-delivery-services), aem-testing for test quality, aem-security for a dedicated security pass.
---
name: aem-code-review
description: >
Reviews AEM code changes — pull requests, diffs or content packages — against a severity-ranked checklist covering security and XSS contexts, resource handling, performance and cacheability, Sling Models, OSGi services, components and dialogs, Cloud Service compatibility, package filters and index names, dispatcher and CDN rules, headless and Universal Editor concerns, tests and accessibility, and returns a findings table with a merge verdict. Use this whenever the user asks to review an AEM PR or diff; pastes HTL, a Sling Model, a servlet, an OSGi service, a .cfg.json, filter.xml, a _cq_dialog, a clientlib or a dispatcher .any file and asks "is this OK"; mentions context='unsafe', ResourceResolverFactory, loginAdministrative, QueryBuilder, @Model, sling.servlet.paths, a SonarQube or Cloud Manager code-quality failure; or wants a pre-merge self-review. Also use it when auditing an inherited AEM codebase.
metadata:
technology: AEM
type: code-review
---
# AEM Code Review
> **Targets:** AEM as a Cloud Service 2026.x projects (Maven archetype layout, Core Components), AEM 6.5 noted where different · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/development-guidelines
AEM bugs hide in the gaps between layers: an HTL context, a leaked resolver, a filter mode, a dispatcher rule. Review each change against the runtime it will actually hit — cached publish, several pods, an immutable `/apps` — and for every finding cite the line, name the impact, and give the fix. A review that lists problems without fixes moves the work, it does not reduce it.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Diff size | Review it all | Over ~400 non-generated lines → ask for a split, or review the riskiest layer in depth and say what you did not review |
| Where to start | The layer with the highest blast radius: `filter.xml`, dispatcher, security | A focused PR with one layer — then follow the diff order |
| Severity of an HTL context | `unsafe` → blocker; `html` on RTE output → fine; `html` on a plain textfield → major | Never wave `unsafe` through because "the value is ours" |
| A `replace`-mode filter on author-owned content | Blocker | Only `/apps` and `/oak:index` are safe in replace mode |
| Generated files (clientlib output, `dist`) | Do not review their diffs | But do check the source changed too |
| Cloud Manager was green | Not evidence | The gates miss filter modes, HTL contexts, cache impact and authoring breakage |
| Verdict | Any blocker, or an untracked major → Request changes | Otherwise Approve, with minor changes if minors exist |
## 2. Before reading the diff
- Get the intent in one sentence — the ticket, or ask. A review without intent becomes a style review.
- Work out **what runs where**: author only, publish, both; request time or background; cached or not. Most AEM findings are really "this is fine on author".
- List the layers touched — `core` Java, HTL and dialogs, `ui.config`, `ui.content` and filters, `dispatcher`, `ui.frontend`, tests — and run the matching sections of `references/review-checklist.md`.
## 3. Severity scale
| Label | Meaning | Blocks merge? |
|---|---|---|
| **[blocker]** | Security hole, content or data loss, resource leak, Cloud Service incompatibility, outage risk | Yes |
| **[major]** | Performance regression, cache-busting, likely bug, missing test for new logic, accessibility failure on a primary flow | Yes, unless deferred with a ticket |
| **[minor]** | Maintainability, non-idiomatic AEM usage, small duplication | No |
| **[nit]** | Style the tooling does not catch | No |
| **[question]** | Intent needed before judging | — |
| **[praise]** | Worth copying | — |
## 4. The findings that matter most
The full layer-by-layer checklist is in `references/review-checklist.md`. These are the ones that appear in almost every AEM review:
- **Unclosed service resolver** → blocker. `try (ResourceResolver rr = factory.getServiceResourceResolver(…))`; never close the request's resolver; never keep one in a field.
- **`loginAdministrative` or an admin session** → blocker. Service user from repoinit, one sub-service per concern.
- **`context='unsafe'`** → blocker. `context='html'` on a plain textfield → major; on RTE output it is correct.
- **`<filter root="/content/acme"/>` with no mode** → blocker: replace mode deletes authored content on every deploy.
- **Path-bound servlet** (`sling.servlet.paths` under `/bin`) → resource type plus selector, or justify the path and show the dispatcher allow.
- **A query with no matching index**, or an index named `mysite-articles-custom-1` instead of `acme.articles-1-custom-1` with `type="lucene"`.
- **A mixed package** (`/apps` plus `/content`) → fails the gates, and mixes immutable with mutable.
- **Ad-hoc POST GraphQL, or a token in a browser bundle** on a headless front end.
- **Secrets or hostnames committed** in a `.cfg.json` → `$[secret:]` / `$[env:]`.
## 5. Reviewing a diff you cannot run
You will usually be reading text, not a running instance. Ask for the three artefacts that turn a guess into a finding:
1. The **query plan** (Explain Query output) for any new or changed query.
2. The **dispatcher validator output**, and a `curl -I` of one affected URL, for any dispatcher or CDN change.
3. A sample **`.model.json`** response for a changed exporter, or the rendered HTML for a changed HTL file.
If they are not available, say which findings are provisional rather than asserting them.
## 6. Deliverable format
```
## Findings
| Severity | File:line | Issue | Why it matters | Fix |
|---|---|---|---|---|
| [blocker] | core/…/TeaserModel.java:42 | Service resolver never closed | Leaks sessions until the pod degrades | try-with-resources around getServiceResourceResolver |
| [blocker] | ui.content/…/filter.xml:6 | `/content/acme` filter in replace mode | Deletes authored pages on every deploy | Add mode="merge" and narrow the root |
| [major] | ui.apps/…/teaser.html:18 | `context='html'` on a plain textfield | Stored XSS if the field is not RTE-filtered | Drop the context, or sanitise with XSSAPI.filterHTML |
## Summary
Verdict: Approve | Approve with minor changes | Request changes
Blockers: <n> Majors: <n> Minors: <n>
Top 3 to address: 1. … 2. … 3. …
Not reviewed: <layers or files skipped, and why>
What's good: <genuine, specific praise>
```
## Checklist
- [ ] Intent understood before the first comment
- [ ] Every touched layer covered, or the gaps named under "Not reviewed"
- [ ] Every finding cites a file and line, an impact and a concrete fix
- [ ] Security, resource handling and `filter.xml` checked even if the PR is "just a component"
- [ ] Index names and package types checked whenever `ui.apps` or `ui.content` changed
- [ ] Cacheability considered for anything that changes a response
- [ ] Tests exist for new logic and regressions for fixed bugs
- [ ] Accessibility and i18n checked on user-facing markup
- [ ] Provisional findings marked as provisional
- [ ] Verdict follows the rule, not the mood of the thread
## Anti-patterns
- **Approving because Cloud Manager passed** → the gates do not see filter modes, HTL contexts or cache impact.
- **Nitpicking Java style while a resolver leaks** → severity order, always; report findings highest first.
- **"Use Core Components"** with no proxy path and no reason → name the component, the version and what it replaces.
- **Skipping the dispatcher and `ui.config` diffs** because they are "not code" → they are the highest-blast-radius files in the repository.
- **Requesting a rewrite to your own patterns** when the repository convention is sound and consistent.
- **A blocker with no line and no realistic impact** → if you cannot show it, mark it as a question.
- **Reviewing generated clientlib output line by line** → check the source instead.
- **No praise at all** → name one thing worth copying; it is how conventions spread.
## Go deeper
- `references/review-checklist.md` — the full layer-by-layer checklist: security, resources, performance, Sling Models, OSGi, components and dialogs, Cloud compatibility, packages and indexes, dispatcher, headless and Universal Editor, EDS, tests, accessibility.
- `oak-index-naming.md` in `../../development/aem-backend-development/references/` — the index grammar to check names against.
- Sibling skills: the development skills own the rules this checklist enforces (`aem-backend-development`, `aem-component-development`, `aem-frontend-development`, `aem-dispatcher`, `aem-headless`, `aem-edge-delivery-services`), `aem-testing` for test quality, `aem-security` for a dedicated security pass.