Org Skills

aem-code-review

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.

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

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

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.

Skill contents

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.

References

Deeper material the agent loads only when needed.