Imported from paialex/ai-skills-bank (skills/aem-architect/SKILL.md). Install upstream with npx skills add paialex/ai-skills-bank --skill aem-architect. Copyright stays with the author.

AEM Architect Skill

Enterprise-grade AEM solution design and implementation guidance.

Workflow Routing

Route to the appropriate workflow based on the request:

Diagram Request Detection

Use the AEMDiagrams workflow when the user mentions:

• "diagram", "flowchart", "sequence diagram", "architecture diagram"
• "visualize", "draw", "show me", "illustrate"
• "mermaid", "ASCII art", "box diagram"
• "component structure", "request flow", "cache flow"
• "service dependencies", "class diagram", "state diagram"

Main Workflow

Follow this structured workflow for every AEM implementation request:

Phase 1: Requirements Gathering

Step 1.1: Ask for User Preference

First, ask the user:

"Would you like me to ask you some discovery questions to provide a more precise and tailored solution?

• Yes - I'll ask targeted questions about your requirements
• No - I'll proceed autonomously based on best practices and available context"

Step 1.2: Check for Attached Requirements

If the user has attached a file (.txt, .doc, .docx, or .md):

1. Read and analyze the file for requirements
2. Extract answers to the discovery questions below from the document
3. If user accepted questions in Step 1.1, ask additional precision questions for any gaps or ambiguities found

Step 1.3: Discovery Questions (if user accepted)

Ask relevant questions from these categories:

Component Architecture

• Component type? (content, structural, container, navigation)
• Extend AEM Core Components or fully custom?
• Required dialog fields? (text, image, pathfield, multifield, nested)
• Target environment? (author, publish, or both)

Performance & Caching

• Expected traffic volume? (low, medium, high, enterprise-scale)
• Caching strategy? (aggressive, moderate, dynamic)
• CDN integration required?

Integration

• Headless/hybrid JSON APIs required?
• External service integrations?
• GraphQL for Content Fragments?
• SPA framework integration?

Phase 2: Analysis & Planning

Step 2.1: Present High-Level Overview

After gathering requirements (or analyzing autonomously), present:

Understanding Summary

Based on my analysis, here's what I understand about your requirements:

• [Bullet points summarizing the project scope]
• [Target environment and architecture]
• [Key components and features needed]
• [Performance and caching considerations]
• [Integration points]

Step 2.2: Present TODO List

Create and present a numbered task list:

Implementation Plan

I will implement the following tasks:

1. Task 1: Description
2. Task 2: Description
3. Task 3: Description ...

Would you like to proceed with this plan, or do you have any changes to propose?

Step 2.3: Wait for User Approval

• If user approves → Proceed to Phase 3
• If user proposes changes → Update the plan and present again
• Do NOT start implementation until user confirms

Phase 3: Implementation

Execute the approved TODO list:

1. Create component structure
2. Implement Sling Model with proper injectors
3. Design dialog using Granite UI patterns
4. Configure ClientLibs with bundling strategy
5. Set up Dispatcher rules
6. Provide testing guidance

Phase 4: Validation

Present completed work with:

• Summary of what was implemented
• File locations and structure
• Testing recommendations
• Cloud Manager quality gate considerations

Reference Documentation

Read the appropriate reference based on the task:

Workflows

Core References (in this skill)

External Guides (in project root)

Quick Reference: Component Creation

Component Structure

/apps/myproject/components/mycomponent/
├── .content.xml                    # Component definition
├── _cq_dialog/.content.xml         # Author dialog
├── _cq_editConfig.xml              # Edit configuration
├── mycomponent.html                # HTL template
└── clientlib/                      # Component CSS/JS

Component Definition

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
    xmlns:cq="http://www.day.com/jcr/cq/1.0"
    xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
    jcr:primaryType="cq:Component"
    jcr:title="My Component"
    jcr:description="Description"
    componentGroup="My Project - Content"
    sling:resourceSuperType="core/wcm/components/title/v3/title"/>

Sling Model Pattern

@Model(
    adaptables = {Resource.class, SlingHttpServletRequest.class},
    adapters = {MyComponent.class, ComponentExporter.class},
    resourceType = MyComponentImpl.RESOURCE_TYPE,
    defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME,
          extensions = ExporterConstants.SLING_MODEL_EXTENSION)
public class MyComponentImpl implements MyComponent {

    static final String RESOURCE_TYPE = "myproject/components/mycomponent";

    @ValueMapValue
    private String title;

    @OSGiService
    private MyService myService;

    @Override
    public String getTitle() { return title; }
}

Common Dialog Fields

For complete field examples, see references/dialog-field-types.md.

Caching Decision Tree

Is content personalized?
├── YES → No Dispatcher cache
│         └── Use client-side personalization or ESI
└── NO → Cache at Dispatcher
         ├── Static asset (JS/CSS/images)?
         │   └── Long TTL (1 year) + content-hash
         ├── HTML content?
         │   └── Moderate TTL (5-60 min) + statfileslevel
         └── API/JSON?
             ├── Public → TTL based on freshness needs
             └── Private → No Dispatcher cache

Statfileslevel Reference

Security Checklist

Dispatcher Filters (Default Deny)

/filter {
    /0001 { /type "deny" /glob "*" }
    /0100 { /type "allow" /method "GET" /url "/content/mysite/*" }
    /0200 { /type "allow" /method "GET" /url "/etc.clientlibs/*" }
    /0300 { /type "allow" /method "GET" /url "/content/dam/*" }
    /0900 { /type "deny" /url "/bin/*" }
    /0901 { /type "deny" /url "/system/*" }
    /0902 { /type "deny" /url "*.infinity.json" }
}

Service User Pattern

try (ResourceResolver resolver = resolverFactory.getServiceResourceResolver(
        Map.of(ResourceResolverFactory.SUBSERVICE, "myproject-service-user"))) {
    // Minimal permissions operations
}

Cloud Service Specifics

When developing for AEMaaCS, always read references/cloud-service-guidelines.md for:

• Cluster-aware code: Instances can stop anytime
• No local state: Disk is ephemeral
• Sling Jobs: For reliable background tasks
• HTTP timeouts: Always set connect/read timeouts
• Rate limiting: Handle 429 with exponential backoff
• Touch UI only: No Classic UI support
• Immutable repository: /libs and /apps are read-only

CI/CD Quality Gates

Common Pitfalls

1. JCR queries in render path → Use content hierarchy traversal
2. Hardcoded paths → Use context-aware configuration
3. Unclosed ResourceResolvers → Use try-with-resources
4. Deep multifield nesting → Consider child nodes
5. Missing Dispatcher filters → Default-deny approach
6. Admin sessions in code → Use service users
7. Untested cache invalidation → Verify statfileslevel
8. Large inline dependencies → Lazy load heavy scripts
9. Skipping Core Components → Extend before building custom
10. Ignoring Cloud Manager gates → Fix locally first