
aem-6-5-lts
All AEM 6.5 LTS and AMS skills: Dispatcher config authoring and hardening, workflow design and debugging, replication agent configuration, content activation, programmatic Replication API, lifecycle orchestration, and troubleshooting, and project bootstrap.
- version
- 1.0.0
- GitHub stars
- 332
Install
/plugin install aem-6-5-lts@adobe-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 5
AEM 6.5 LTS Replication
Route user requests to the appropriate specialist skill based on intent.
Intent Router
| User Intent | Skill | Path |
|---|---|---|
| Configure replication agents (default, dispatcher flush, reverse replication) | Configure Replication Agent | configure-replication-agent/SKILL.md |
| Activate or deactivate content using UI or workflows | Replicate Content | replicate-content/SKILL.md |
| Use Replication API programmatically in custom code | Replication API | replication-api/SKILL.md |
| Diagnose blocked queues, connectivity issues, or distribution problems | Troubleshoot Replication | troubleshoot-replication/SKILL.md |
| End-to-end workflows: new environment setup, incident response, performance optimization | Replication Orchestrator | replication-orchestrator/SKILL.md |
How to Use
- Match the user's request to one row in the Intent Router table above.
- Read the linked SKILL.md for that specialist skill.
- Follow the workflow and guidance defined in that skill.
- For complex scenarios spanning multiple skills (e.g., configure agent then troubleshoot), start with the primary intent and cross-reference as needed.
- If the request doesn't clearly match a single row, ask the user to clarify before proceeding.
Skill Overview
- Configure Replication Agent — Set up default, Dispatcher Flush, reverse, and multi-publish agents. Use for first-time setup, adding publish instances, or reconfiguring agents.
- Replicate Content — Activate/deactivate content via Quick Publish, Manage Publication, Tree Activation, Package Manager, workflows, or scheduled activation. Use for publishing/unpublishing pages, assets, or DAM content.
- Replication API — Programmatic replication via
Replicator,ReplicationOptions,ReplicationStatus,AgentManager,ReplicationQueue, andReplicationListener. Use for custom code integration, bulk operations, workflow process steps, or servlets. - Troubleshoot Replication — Diagnose blocked queues, connection errors, missing content, agent misconfiguration, and stuck jobs. Use when replication fails, underperforms, or content isn't distributing.
- Replication Orchestrator — Coordinates multi-step scenarios across the other sub-skills: environment setup, incident response, performance optimization, migration prep.
Common Workflows
First-Time Setup
- Use Configure Replication Agent to set up default agent
- Use Replicate Content to test with a sample page
- If issues occur, use Troubleshoot Replication
Production Operations
- Use Replicate Content for day-to-day publishing
- Use Replication API for automated/bulk operations
- Use Troubleshoot Replication when issues arise
Advanced Integration
- Use Replication API to understand available methods
- Use Configure Replication Agent to understand agent configuration
- Use Troubleshoot Replication for debugging custom replication code
Foundation References
Shared reference materials used across all replication skills:
- Agent Types: Default, Dispatcher Flush, Reverse, and Static agents
- Queue Mechanics: FIFO processing, retry logic, queue management
- AEM 6.5 LTS Guardrails: Service users, timeouts, batch limits, best practices
- API Quick Reference: Replicator, ReplicationOptions, ReplicationStatus methods
Official Documentation
All skills reference official Adobe AEM 6.5 LTS documentation:
Related Skills
- AEM Workflow: Integrate replication with approval workflows
- Dispatcher: Configure Dispatcher Flush agents for cache invalidation
Migration to AEM as a Cloud Service
AEM as a Cloud Service uses the Sling Distribution API instead of replication agents. If planning migration:
- Review Cloud Service Distribution Documentation
- For code migration patterns, use the
code-assessmentskill:skills/aem/cloud-service/skills/code-assessment/replication/SKILL.md - Avoid agent-specific coupling (filter by agent ID) to reduce migration complexity
AEM 6.5 LTS Workflow
Route user requests to the appropriate specialist skill based on intent.
Intent Router
| User Intent | Skill | Path |
|---|---|---|
| Create a workflow model, add steps, design OR/AND splits, configure variables | Model Design | workflow-model-design/SKILL.md |
| Implement a custom WorkflowProcess step, ParticipantStepChooser, OSGi service registration | Development | workflow-development/SKILL.md |
| Start a workflow from code, HTTP API, Timeline UI, Manage Publication, replication triggers | Triggering | workflow-triggering/SKILL.md |
| Configure a launcher, auto-start on asset upload, overlay OOTB launcher | Launchers | workflow-launchers/SKILL.md |
| Workflow stuck, failed step, missing Inbox task, stale instances, thread pool exhaustion, purge | Debugging | workflow-debugging/SKILL.md |
| Classify a workflow incident, determine required logs, JMX diagnostics, Splunk queries | Triaging | workflow-triaging/SKILL.md |
| End-to-end lifecycle or requests spanning multiple concerns | Orchestrator | workflow-orchestrator/SKILL.md |
How to Use
- Match the user's request to one row in the Intent Router table above.
- Read the linked SKILL.md for that specialist skill.
- Follow the workflow, references, and output contract defined in that skill.
- For broad or ambiguous requests that span multiple concerns, use the Orchestrator which coordinates across all specialist skills and loads foundation references.
6.5 LTS / AMS Capabilities
| Capability | Detail |
|---|---|
| JMX | Full access via Felix Console (/system/console/jmx) or JMX client |
| Retry failed items | JMX retryFailedWorkItems or Inbox Retry |
| Stale detection | JMX countStaleWorkflows |
| Stale restart | JMX restartStaleWorkflows(dryRun=true) then execute |
| Purge | JMX purgeCompleted(dryRun=true) or Purge Scheduler |
| Log access | Direct filesystem (crx-quickstart/logs/) or AMS log access |
| Config changes | Felix Console, OSGi config in repo, or CRX/DE |
6.5 LTS Guardrails
| Rule | Detail |
|---|---|
Avoid editing /libs | Use overlays under /apps or store at /conf/global |
| Model design-time path | /conf/global/settings/workflow/models/<id> (preferred) or /etc/workflow/models/<id> (legacy) |
| Model runtime path (for API calls) | /var/workflow/models/<id> |
| Launcher config paths | /conf/global/settings/workflow/launcher/config/ (preferred) |
| Service users | Use ResourceResolverFactory.getServiceResourceResolver() with a sub-service; avoid loginAdministrative |
| OSGi annotations | DS R6 preferred; Felix SCR still supported on 6.5 LTS |
| Deploy via | Package Manager, Maven + Content Package Plugin |
Specialist Skills
- workflow-model-design/SKILL.md — model structure, step types, variables, and model XML
- workflow-development/SKILL.md — WorkflowProcess, ParticipantStepChooser, metadata, and error handling
- workflow-triggering/SKILL.md — Timeline UI, Manage Publication, WorkflowSession API, HTTP API, and replication triggers
- workflow-launchers/SKILL.md — launcher configuration, JCR event binding, and OOTB overlay
- workflow-debugging/SKILL.md — stuck workflows, failed steps, JMX remediation, thread pools, and purge
- workflow-triaging/SKILL.md — symptom classification, JMX diagnostics, log patterns, Splunk queries, and data gathering
- workflow-orchestrator/SKILL.md — full lifecycle orchestration across all skills
AEM 6.5 LTS Dispatcher
Route user requests to the appropriate specialist skill based on intent.
Intent Router
| User Intent | Skill | Path |
|---|---|---|
Create, modify, review, or harden dispatcher config files (.any, vhost, rewrite, cache, filter) | Config Authoring | config-authoring/SKILL.md |
Conceptual questions (statfileslevel, filter rules, URL decomposition, cache invalidation, rewrite behavior, security headers) | Technical Advisory | technical-advisory/SKILL.md |
| Investigate runtime incidents, failures, or cache anomalies | Incident Response | incident-response/SKILL.md |
| Optimize cache efficiency, latency, and throughput | Performance Tuning | performance-tuning/SKILL.md |
| Security audit, threat model, exposure control, header hardening | Security Hardening | security-hardening/SKILL.md |
| End-to-end lifecycle (design → implement → validate → release → incident) or requests spanning multiple concerns | Workflow Orchestrator | workflow-orchestrator/SKILL.md |
How to Use
- Match the user's request to one row in the Intent Router table above.
- Read the linked SKILL.md for that specialist skill.
- Follow the workflow, references, and output contract defined in that skill.
- For broad or ambiguous requests that span multiple concerns, use the Workflow Orchestrator which coordinates across all specialist skills.
MCP Tool Contract
All specialist skills share the same core-7 MCP tool set:
validate— static config validationlint— deep/order-aware lintingsdk— SDK check-files and diff-baselinetrace_request— trace a request through dispatcherinspect_cache— inspect cache statemonitor_metrics— runtime metricstail_logs— log tailing
Specialist Skills
- config-authoring/SKILL.md — config file design, edits, and validation
- technical-advisory/SKILL.md — policy, documentation, and evidence planning
- incident-response/SKILL.md — runtime incident triage and remediation
- performance-tuning/SKILL.md — cache and throughput optimization
- security-hardening/SKILL.md — security audit and hardening
- workflow-orchestrator/SKILL.md — full lifecycle orchestration across all skills
Ensure AGENTS.md and CLAUDE.md (bootstrap)
Mandatory order (all cases)
Before any other work — including dispatcher, create-component, code edits, MCP, or answers — the agent MUST:
- Check whether
AGENTS.mdexists at the workspace (repository) root. - If it exists → skip this skill entirely and continue with the user's request.
- If it does not exist and the repo is an AEM 6.5 LTS project (see Gate check) → run this skill completely first (create
AGENTS.mdandCLAUDE.mdif missing), then fulfill the user's original request.
This applies to every user message and any intent (bugs, features, questions, dispatcher, etc.) until AGENTS.md is present. Do not defer bootstrap to "after" the main task.
It creates AGENTS.md and CLAUDE.md at the repository root so every AI coding agent (Claude Code, Cursor, etc.) gets project guidance, optionally tailored using the module catalog and add-on detection.
Gate check
- Look for
AGENTS.mdat the workspace root. If it exists → skip, move on. - Verify this is an AEM 6.5 LTS (or AMS 6.5) Maven project, not AEM as a Cloud Service:
- Root
pom.xmlexists. - Exclude (Cloud Service): if the project's primary AEM API dependency is
com.adobe.aem:aem-sdk-apior packaging/parent clearly targets Cloud Service only — use the cloud-serviceensure-agents-mdskill instead, not this one. - Include (6.5 / AMS):
pom.xmlreferencescom.adobe.aem:uber-jar(any classifier), orcq-quickstart/ product dependency coordinates for 6.5, or a property such asaem.version/cq.quickstart.versionin the 6.5 line, and typical AEM module names appear in<modules>(core,ui.apps,dispatcher, etc.) when present. If not an AEM project → skip.
- Root
Steps
1. Resolve project name
Check in order:
- Root
pom.xml→<name>element (preferred, usually human-readable). - Root
pom.xml→<artifactId>, then humanize: strip leadingaem-, replace-with spaces, title-case (e.g.aem-guides-wknd→WKND,my-site→My Site). - Directory name of the workspace.
- Fallback:
"AEM 6.5 LTS Project".
2. Discover modules
Read root pom.xml <modules> section. For each <module>, confirm the directory actually exists.
Build a list of present modules.
3. Detect add-ons and frontend type
Scan the project for:
| Signal | Add-on / variant |
|---|---|
pom.xml depends on cif-connector or aem-core-cif-components | CIF (Commerce) |
ui.frontend/package.json contains react or @adobe/aem-react-editable-components | React SPA |
ui.frontend/package.json contains @angular/core or @adobe/aem-angular-editable-components | Angular SPA |
ui.frontend has no clientlib.config.js and pom.xml references frontend-maven-plugin but outputs no clientlibs | Decoupled frontend |
pom.xml depends on aem-forms-* or forms.core | AEM Forms |
Module ui.frontend.react.forms.af exists | Headless Forms |
pom.xml uses precompiled-scripts-provider | Precompiled Scripts |
If none of these are detected, treat as General Webpack frontend (the default archetype).
4. Generate AGENTS.md
Read the template at references/AGENTS.md.template. Apply the following adaptations:
a. Title
Replace {{PROJECT_NAME}} with the resolved project name.
b. Add-ons section
If any add-ons were detected (CIF, Forms, Headless Forms, Precompiled Scripts), insert an "Add-ons and extensions" section after the intro paragraph. Use descriptions from the references/module-catalog.md add-ons table. If none detected, omit the section entirely.
c. Modules section
Only include modules that actually exist in the project. For each module, use the matching description from the module catalog. Pay attention to:
ui.frontend— use the variant that matches the detected frontend type (General, React, Angular, Decoupled).dispatcher— only include if thedispatcherdirectory exists.it.tests/ui.tests— only include if they exist.
d. Build commands
- Include frontend commands (
npm run build,npm start) only ifui.frontendexists. - Include dispatcher validate command only if
dispatchermodule exists. Usehttpd -t -f <path-to-httpd.conf>orapachectl configtest— adjust the config path to match the project layout. - For React/Angular SPA, note that
npm startrequires AEM running.
e. Important resources
Always include the base resources from the template. Additionally:
- If React or Angular SPA detected → add SPA Editor and framework-specific resources (see module catalog).
- If CIF detected → add Commerce resources.
- If Forms detected → add Forms resources.
- If Decoupled frontend → add headless / external-frontend resources.
5. Create CLAUDE.md
If CLAUDE.md does not exist at the workspace root, create it with exactly this content (so Claude/Cursor picks up project guidance):
@AGENTS.md
Do not overwrite an existing CLAUDE.md.
6. Inform the user
Briefly tell the user:
"I created
AGENTS.mdandCLAUDE.mdin your project root with guidance tailored to your project structure. These help AI coding agents understand your project."
Then continue with the user's original request.
Reference files
| File | Purpose |
|---|---|
| references/AGENTS.md.template | Base template with {{PROJECT_NAME}} placeholder and all default sections |
| references/module-catalog.md | Module descriptions, add-on descriptions, conditional resources — the source of truth for adapting the template |
Rules
- Never overwrite an existing
AGENTS.mdorCLAUDE.md. Only create when missing. - Never hallucinate modules. Only list modules whose directories actually exist.
- Keep the generated AGENTS.md clean — no skill metadata, no comments about "generated by skill".
- Project name should be human-readable (e.g. "WKND Sites Project", "My Site"), not only a raw artifactId unless that is the desired title.
- Do not add sections that tell agents to use specific MCP servers, Cursor/Claude skills, or how to discover tools. Coding assistants pick those up from product configuration and tool metadata; if something is not discovered, fix metadata or MCP setup — do not duplicate that in AGENTS.md.
- The resource links must point to AEM 6.5 and ecosystem docs on Experience League (
experienceleague.adobe.com/en/docs/experience-manager-65/..., shared HTL/Dispatcher/Learn paths where appropriate). Do not use AEM as a Cloud Service-only URLs as the primary reference for this skill.
Tuning Oak Query Indexes
Overview
An Oak query only uses an index for the parts the index actually covers. Any WHERE/ORDER BY/fulltext
field without a matching, correctly-flagged property definition gets evaluated node-by-node in memory —
same for a wrong nodetype or path scope, even if every field is indexed. This skill is the procedure
for finding exactly which fields/conditions aren't covered and what index-definition change fixes each
one.
Ground truth for every claim below: the AI agent indexing guide, bundled alongside this skill so it works the same way regardless of which codebase it's copied into. Read it on demand for exact property tables, defaults, cost-model details, and edge cases — this skill is the checklist, not the reference.
This skill assumes nothing about the codebase it's used in beyond "you have a query and an index
definition." It does not require an AEM instance, a running Oak repository, or a checkout of Oak's own
Java source — those only strengthen confidence where noted (step 6 and the "explain can't reach this"
fallback below), never a requirement; the core procedure — read the query, read the index definition, find
the gap, propose the fix — works from the two artifacts alone. Index definitions in a
real project are often FileVault XML (.content.xml under an /apps/.../install content package,
jcr:primaryType="oak:QueryIndexDefinition" and friends), not raw JSON — read them the same way; the
property names and semantics are identical, only the serialization differs.
Procedure
Required input — the index definition(s). This skill does not run without them. The whole
assessment is a comparison of a query against the index definition(s) it could use, so the index
definition is mandatory input, not an optional aid. If it was not provided, ask for it — accept any
of: a FileVault .content.xml under an /apps/.../install package, a JSON export, or the live dump at
GET /system/console/status-oak-index-defn.json (admin auth). If none can be obtained, skip this skill
and say so explicitly — do not emit a coverage assessment from the query alone. A guess about what is
indexed reads as a finding and gets acted on as one; no answer is better than a wrong one. (The query is
the other required input — provide it directly, or build the inventory with the bundled
extracting JCR queries guide.)
Preconditions: steps 1 and 6 below both mention live-instance tools (explain, the Felix
InventoryPrinter, Oak's trunk test suite) — neither is required. Given the query text and the
index definition(s), skip those tools' sub-bullets, do steps 2-5 and 7 as pure static analysis, and report
per the final section with verification stated as reasoned-but-unproven.
-
Get the query and every index definition it could plausibly use — not just the one you assume applies. If you don't already have the query in hand — e.g. asked to audit a whole app/bundle rather than tune one query someone handed you — first follow the bundled extracting JCR queries guide to find every JCR/QueryBuilder query the codebase actually issues (including ones assembled programmatically through wrapper/helper/DAO code, which a text grep alone misses); its output (construction site + every trigger/caller path) is the input to this skill's assessment, one query at a time. If no live instance is reachable, work from every index definition you were actually given and say so in the report (§ Report shape) — candidate selection is then reasoned, not confirmed. If a live instance is reachable,
explaintells you which index actually gets picked, which is stronger than reasoning from the definitions alone; to enumerate every index definition in the repository (including non-root ones a per-path lookup would miss), use the FelixInventoryPrinterstatus pageoak-coreitself registers — it works on any Sling/Felix-based Oak deployment, not just AEM:GET /system/console/status-oak-index-defn.json(admin auth). It dumps every index definition (config only, no hidden:data/:indexstorage nodes) in the samenam:/str:/dat:/... type-prefixed JSON encoding oak-run's--index-definitions-fileuses — one request beats guessing candidate index names one at a time. -
Segregate every query into two sections before analyzing anything — Section A (static fields) and Section B (dynamic fields):
- Section A — static fields: the property path/name the query filters, orders, or searches on is
fixed in source — a literal string or a named constant — even if the value compared against it
varies at runtime (a caller-supplied ID, a loop variable, a request parameter used only as a value).
A query stays in Section A as long as you can point at the exact
WHERE/ORDER BYfield name without guessing. - Section B — dynamic fields: the property path/name itself is not fixed in source — it comes from
OSGi config (
detectMetadataField-style properties), a request/predicate-map key, a content-authored query (dam:querynodes, Smart Collections), or a script/native query string. You cannot state which property the index needs to cover without external input. Assess Section A fully — that's the primary deliverable. For Section B, do not guess the likely or default field name and assess that guess as if it were the query's real target. Instead, list each Section B query with the specific missing input (e.g. "OSGi config value ofdetectMetadataField", "thetyperequest parameter passed to this servlet") and ask the user for it. Only fold a Section B query into a real assessment once the user supplies the concrete field name(s) it actually uses in their deployment — treat that answer the same as a Section A fact from that point on.
Excuse to assess anyway Reality "The default value is probably X, I'll note the caveat" A caveated guess still reads as an assessment and gets acted on as one — if the deployment overrides the config, the whole coverage table is wrong. State the missing input and stop instead of assessing the default. "Partial assessment is still useful" Partial-but-wrong is worse than no assessment — it's indistinguishable from a verified finding in the report. Segregate it into Section B and ask. "I already covered the default case in Technique 1" Knowing the default is not the same as knowing the configured value. Confirm before assessing, don't infer. "Asking breaks the flow of the report" The report is still complete — Section A stands on its own. Section B becomes assessable the moment the user answers. - Section A — static fields: the property path/name the query filters, orders, or searches on is
fixed in source — a literal string or a named constant — even if the value compared against it
varies at runtime (a caller-supplied ID, a loop variable, a request parameter used only as a value).
A query stays in Section A as long as you can point at the exact
-
Extract every field/construct the query touches:
WHEREequality/range/IN/IS NULL/IS NOT NULL,ORDER BYcolumns,contains(...)/fulltext,rep:facet/rep:similar/rep:suggest/rep:spellcheck, path restriction (ISDESCENDANTNODE///), and the query's own nodetype restriction (FROM [type]/ XPathelement(*, type)).- AEM QueryBuilder predicate maps — the field name is usually a value, not a key. For the
property,relativedaterange,daterange,boolproperty, andsimilarpredicate types, the map key (1_property,5_relativedaterange.property, ...) is just the predicate-type token plus its group index — it names which predicate, not which JCR property. The actual field the index needs to cover is the string value assigned to that key, e.g.map.put("1_property", "jcr:content/hasValidMetadata")→ the field to check index coverage for isjcr:content/hasValidMetadata, read from the value, not from the literal text1_property. Same pattern formap.put("1_relativedaterange.property", "jcr:created")→ field isjcr:created. Don't let this trip up the Section A/B call in step 2: the field name here is still a hardcoded string literal in source (Section A), even though it doesn't look like a typicalWHERE-clause field the way a SQL2/XPath condition does — it only becomes Section B if that value itself is a variable/request parameter rather than a literal.
- AEM QueryBuilder predicate maps — the field name is usually a value, not a key. For the
-
For each field, look up the required flag (table below) and check the index has a property definition with a matching
namecarrying it. -
Check the two scoping gotchas before anything else — these skip the index entirely regardless of how well the fields are indexed, and are the most common reason an apparently-correct index isn't picked:
- Nodetype scoping: does the query's own
FROM/element()restriction name the index's declared type (or a subtype)? If the query is unrestricted (bare*/ implicitnt:base) but the index only declares rules for one type (declaringNodeTypeson a property index, orindexRulesnot includingnt:baseon Lucene), the index is invisible to the planner — costInfinity, or absent from the candidate list entirely. Fix by adding the nodetype restriction to the query, not by changing the index. - Path scoping (Lucene only): do
includedPathsandqueryPathsmatch each other, and does the query's actual path restriction fall inside them? LeavingqueryPathsat its default (/) while narrowing onlyincludedPathsis worse than not being selected — the index gets picked outside its real coverage and silently returns fewer results than actually exist.
- Nodetype scoping: does the query's own
-
Verify empirically, don't just reason from the spec. Run
explain <query>(or the AEM Query Performance tool). Confirm: (a) the expected index appears in the candidate/cost log at all, (b) its cost beats every alternative including traversal, (c) the plan shows notraverseand no unindexed residual condition for a field you believe is covered. A finite cost does not by itself prove a given condition is served natively — live-confirmed: an index selected at a normal-looking finite cost (beating traversal, due to nodetype/path scoping alone) had a plan whose actualluceneQuerywas a bare*:*, meaning an equality condition on an unindexed property was still being evaluated as a residual in-memory filter, not pushed into the index at all. Always read the loggedluceneQuery/plan text itself for the specific field you care about, not just whether some index got a finite cost.explainonly tells you which index and cost/plan get picked — it says nothing about whether a feature that doesn't work through the cost-plan mechanism actually behaves correctly: suggestions (rep:suggest), spellcheck (rep:spellcheck), facet counts, similarity ranking (rep:similar), andrep:nativeall fall in this category and need their own verification, not anexplaincheck. See the indexing guide's "Verifying featuresexplaincan't reach" (Appendix B) for the two ways to get real signal (a live-instance config/MBean cross-check, or the exact Oak trunk unit tests to run) — and if neither is available, say so plainly in the report rather than guessing.
-
Identify the single existing index the fix belongs on before writing any change. Never invent a brand-new index or silently pick one of several plausible candidates — the target index changes the whole recommendation (which properties it already has, its current tags/weight/reindex history), so getting it wrong makes step 8's "corrected index definition" wrong too.
- Live instance reachable: run
explainon the query as-is (even though you expect a gap — the candidate list and per-index cost the response returns is exactly what's needed here, not just a pass/fail).explain's response enumerates every candidate index it considered with its cost, not just the winner — read that list, not just the top line. The lowest-cost index that also matches the nodetype/path scoping from step 5 is the target. State the cost numbers you read, not just the index name, so the choice is checkable. - No live instance: enumerate every index definition you were given whose nodetype+path scoping
(step 5) matches the query — these are the only real candidates regardless of how many index files
exist in the repo. Then:
- Exactly one candidate matches → that's the target, proceed.
- Zero candidates match → there is no existing index to extend; say so explicitly and propose a new index only as a last resort (this is the one case where inventing an index is correct, and it still needs to be called out as such, not presented as "the fix" silently).
- More than one candidate matches (contending indexes) → do not silently pick one — this is
exactly the "a property IS indexed, but a different, cheaper index still wins" mistake from the
list above, except now you're the one choosing without the cost data
explainwould have given you. Present the contenders side by side — for each: which of the query's fields it already covers, itstags,weight(if set),includedPaths/queryPaths, and how narrowly it's already scoped — and ask the user which index they want the change applied to. Do not propose a corrected definition for any of them until the user picks one.
- Live instance reachable: run
-
Propose the smallest fix that gives every field its required flag. Prefer one cohesive index per nodetype over several overlapping single-purpose ones. Set
reindex: truefor the change, notrefresh: true, unless you can positively confirm no existing content already carries the new/changed property's value —refresh: trueonly makes a new property definition plannable (explain will show it as a candidate); it does not backfill pre-existing documents that already had the value before the definition existed. Live-confirmed: a property added withrefresh: truealone showed up inexplainimmediately, but a real query for a pre-existing document's value returned zero results until a genuinereindex: trueran. If you can't be certain the property is genuinely new to every document, reindex. Before changing the index, check whether tightening the query gets you further for less cost — a more constrained query is always cheaper and safer than a broader index, in this order of preference:- Add/narrow a nodetype restriction (
element(*, T)/FROM [T]) — the single highest-leverage change; see the nodetype-scoping gotcha above. Never use a bare*/nt:baserestriction if the real target type is known. - Add/narrow a path restriction (
ISDESCENDANTNODE///scoped as tightly as the use case allows) — shrinks both the traversal fallback cost and, if the index is path-scoped, keeps it eligible. - Add/tighten property conditions (more selective equality/range conditions push more work into the
index and reduce what's read out of it).
Only after the query is as constrained as the use case genuinely allows should the index definition
itself be widened — widening the index is the more expensive, more permanent change (more storage, more
indexing time, affects every other query that hits it), while tightening the query text is free and
query-request-local. Producing the corrected index definition (the JSON/content diff) is not the same
as applying it — writing it out for review is fine to do unprompted, but actually pushing it to a live
instance (a Sling POST/
curl -F, a.content.xmlcommit, or any other write) is a repository-mutating change like any other and needs the user's explicit go-ahead first, same as the indexing guide's Appendix B requires for its create/modify/delete commands.
- Add/narrow a nodetype restriction (
-
Re-verify with
explainafter the change has been applied (and after the async cycle, if applicable) — confirm no residual/in-memory filtering remains, and anyORDER BYis served by the index, not a full in-memory sort.
Field construct → required index flag
| Query construct | Property index (type=property) | Lucene property definition |
|---|---|---|
Equality / IN | in propertyNames | propertyIndex: true |
IS NOT NULL | in propertyNames (property index has no dedicated existence-only flag) | propertyIndex: true, or the cheaper notNullCheckEnabled: true alone if you never need equality/range/ordering on the value — see the cost note below |
IS NULL | n/a — no mechanism exists for type=property | nullCheckEnabled: true (standalone, propertyIndex not required) |
ORDER BY | not supported | ordered: true + explicit type |
contains(prop, ...) | not supported | analyzed: true |
contains(., ...) (node-scope) | not supported | analyzed: true + nodeScopeIndex: true on every contributing property |
rep:facet | not supported | facets: true |
Range (<,>,<=,>=) | works if in propertyNames | propertyIndex: true + explicit type |
Relative property (a/b/@c) | not supported | name: "a/b/c" |
Function (lower(...), name(), path()) | not supported | function: "..." + propertyIndex/ordered as needed |
Always set an explicit type (Date/Long/Double) on any property used in ORDER BY or a range
condition — without it, values can be compared lexicographically (numeric-looking strings sort
"1","10","2"; unparsed dates sort before all valid ones instead of erroring or being excluded).
Index size / storage cost pitfalls
Every fix in this skill makes a query faster by making the index cover more. That's not free — always surface the tradeoff when a proposed change triggers one of these, don't just add the flag silently:
| Enabling this... | ...costs this |
|---|---|
nodeScopeIndex on any property in a rule | Indexes the node name for every node matching that rule, not just the boosted property — large for broad rules like nt:base. Scope the rule to the narrowest real nodetype before turning this on. |
evaluatePathRestrictions | Slight but real per-document storage increase (stores ancestor-path terms). Only enable on indexes that actually need native path-restriction evaluation (§4.2's queryPaths correctness case), not by default. |
ordered on a property | Increases index size (doc-values field per ordered property). Intended for single-valued properties only — but enabling it on a multi-valued one does not hard-fail: it just logs a WARN and skips the doc-values field for that document, so ORDER BY silently degrades to an unpredictable position for multi-valued documents instead of erroring. Only mark properties ordered that a real ORDER BY actually uses, and don't rely on a hard failure to catch a multi-valued mistake — check your data. |
| Many properties in one broad index "just in case" | Bigger index, slower indexing, and — per the nodetype/path scoping gotchas above — no selection benefit if the query doesn't ask for them. Prefer narrow, cohesive indexes over one large catch-all. |
| A single Lucene index approaching ~2^31 documents | Hard ceiling in the Lucene version Oak ships — the index can stop being openable past this. Split into multiple narrower (nodetype- or path-scoped) indexes (Solr used to be an escape hatch for this; it was removed in Oak 1.82). |
Long text values with no maxFieldLength override | Only the first ~10000 terms per field are indexed by default — a large document field is silently truncated, not indexed in full, which can produce fulltext misses on content past that boundary. |
propertyIndex: true used purely for IS NOT NULL/IS NULL, with no equality/range/ordering ever needed | Wastes storage — propertyIndex indexes every distinct value as its own term in a dedicated field. notNullCheckEnabled/nullCheckEnabled alone (no propertyIndex needed) do the same existence check via one lightweight, unstored term in a shared field across the whole index (:notNullProps/:nullProps) — genuinely cheaper, live-confirmed to work standalone. The flip side: nullCheckEnabled on a broad/generic nodetype where the property is rarely set can itself create an entry for nearly every document (an entry per node without the value) — scope it to a narrow nodetype. |
The general principle: the more constrained a query is, the cheaper and safer it is to serve — a
query naming a specific, narrow nodetype and path is always preferable to a broad nt:base/unscoped one,
independent of whatever the index does. Recommend query tightening first (step 8) before recommending an
index that has to compensate for an unnecessarily broad query.
Common mistakes (each one live-verified during this skill's development)
Beyond the two scoping gotchas in step 5 (a nodetype-scoped index skipped entirely when the query has no
matching restriction; includedPaths/queryPaths mismatches silently returning fewer results):
sync/uniqueon a Lucene property definition, but the index's ownasyncis still a single string (not["async","sync"]/["async","nrt"]) → silently never synchronous, never enforced.- A property IS indexed, but a different, cheaper index still wins → check
weight(lower = cheaper, default5), and re-check the scoping gotchas above on the index you expected to win. - Indexing many unrelated properties into one index "just in case" → prefer one cohesive index per
nodetype; overlapping indexes with different
includedPaths/excludedPathsfor the same nodetype cause ambiguous selection. rep:facet/rep:similarhit the nodetype-scoping gotcha too —rep:facetfails with a hard exception ("... can't be evaluated by traversal") instead of silently falling back like plain fulltext. This only happens when the query actually runs —explainon the same query does not throw; it returns a normal success with atraverse/estimatedEntries: Infinityplan, easy to misread as "fine, just slow." Don't trustexplainsucceeding as proof arep:facetquery works — run it for real, or treat anInfinity-cost traverse plan on a facet query as an early-warning sign it will fail at execution.- A raw
rep:native('idx', 'field:value')query string silently matches nothing iffieldis ananalyzedproperty — its real Lucene field name isfull:field(escape the colon:full\:field:value), not the bare JCR property name. Only non-analyzed (propertyIndex-only) fields use the bare name. Root-caused viaFieldNames.ANALYZED_FIELD_PREFIXand live-confirmed side by side (unescaped form: 0 results;full\:-escaped form: correct match, same index/content) — this is the single most common reason a native query "doesn't work" despite a correct-lookingexplainplan.
Report shape
Structure the report in the two sections from step 2 — never merge them:
Section A — static fields (assess fully)
For every Section A query, produce:
- A table: field/construct → covered? → what's missing.
- Root cause per uncovered field (which failure mode from the table/mistakes above — including the two scoping checks, even when they pass).
- Whether the query itself can be more constrained first (nodetype, then path, then property conditions — see step 8) — call this out even if the eventual answer is "no, it's already as narrow as the use case allows."
- Which index the fix targets and why (step 7): the
explain-confirmed candidate list with costs, or the single statically-matched candidate, or — if multiple indexes contend and no live instance was available to break the tie — the side-by-side contender comparison and a question to the user asking which one to change, with no corrected definition given for any of them until they answer. - The corrected index definition (full JSON or content diff) for the index identified in item 4, with a one-line justification per change, and the storage/size tradeoff called out explicitly for any change that triggers one of the pitfalls above (don't let a size cost pass silently just because it fixes the query).
- The
explaincommand to run to verify, and what a passing result looks like — but if no live Oak instance is available, say so plainly and present the static analysis as reasoned-but-unproven rather than skipping verification silently.
Section B — dynamic fields (ask, don't assess)
For every Section B query, list the construction site and the exact missing input (named OSGi property, request parameter, config key, or "arbitrary content-authored query — no fixed field exists"), then ask the user for it. Do not include a coverage table, root cause, or corrected index definition for a Section B query until the user supplies the concrete field name(s) — at that point re-run steps 4-9 on it and move it into Section A's report format for that query.
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/aem/6.5-lts
- Author
- Adobe
- Category
- Aem
- License
- Apache-2.0
- Keywords
- adobe, aem, aem6.5, 6.5-lts, ams, dispatcher, workflow, replication
More from adobe/skills
All 19- aem-cloud-servicev1.4.4
- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1
- aem-eds-personalizationv1.0.0
- aem-forms-edge-delivery-servicesv1.0.1
- aem-project-managementv1.0.1
- app-builderv1.0.0
- commerce-app-management
- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0
- stardustv0.39.4
- webv1.0.0
- workfrontv2.0.0
- adobe-analyticsv1.0.0
- adobe-cjav1.0.1
- adobe-for-developersv1.0.0