AEM Component Creation Skill

Creates complete AEM components following Adobe best practices.

Configuration Gate Check — Do This First

This configuration check needs to happen first because without it, the skill will use incorrect project paths and package names, causing every generated file to be wrong.

First tool call: Read .aem-skills-config.yaml in the project root (same level as pom.xml).

Check: Does the file exist and does it have configured: true?

If NOT configured, Display This Message and Stop:

Project configuration required!

Before creating components, configure your project settings in:
`.aem-skills-config.yaml` (in your project root, same level as pom.xml)

Open the file and update:
- project: Your AEM project name (e.g., 'mysite', 'wknd')
- package: Your Java package (e.g., 'com.mysite.core')
- group: Your component group (e.g., 'MySite Components')
- configured: true

After updating, ask me to create the component again.

Why you should not explore the codebase when unconfigured:

Doing any of the following before configuration is set will lead to incorrect assumptions and wasted effort:

• Reading any other repository files
• Listing directories to "understand the project"
• Checking existing components for patterns
• Looking at pom.xml, Java files, or folder structures
• Inferring values from any source

The config file is the single source of truth for project values — skipping it leads to wrong paths and package names in every generated file.

No Hallucination Rule

Only create the exact fields the user specified — adding extra fields creates authoring confusion and maintenance burden, and renaming fields breaks content contracts.

Load reference for full rules: references/no-hallucination-rules.md

Workflow Overview

Step 0: Configuration Validation

0.1 Read Configuration

1. Read .aem-skills-config.yaml from the project root
2. Check that configured: true
3. Read project, package, and group values

0.2 Validate — Use Only the Config File

Do not infer project values from the file system, existing components, Java files, pom.xml, or prior knowledge. These sources may be outdated or inconsistent — .aem-skills-config.yaml is the single source of truth because the user explicitly sets it.

0.3 Load Conventions

1. Read references/aem-conventions.md for file structure templates, naming conventions, and patterns

0.4 Project State Analysis (after configuration validated)

1. Check Component Name Uniqueness - Look in /apps/[project]/components/
2. Check Model Class Conflicts - Look in core/src/main/java/[package-path]/models/
3. Analyze Existing Patterns - Review 1-2 recent components for style reference

Step 1: Extract & Validate Component Name

• Parse component name from user's message (ask if not provided)
• Normalize to lowercase kebab-case (e.g., My Component -> my-component)
• Validate: starts with letter, only letters/numbers/hyphens, no consecutive hyphens

Step 1.5: Component Extension Decision

When user says "extend {component}":

Tier 1: Check Project Components First

• Search /apps/{project}/components/{component}
• If found -> Use as sling:resourceSuperType

Tier 2: Check Core Components

Tier 3: Not Found - Ask user for clarification.

For extension patterns, load: references/extending-core-components.md

Step 1.6: Core Component Extension Requirements

Required when extending with "hide", "remove", "add custom field", or "override" (these operations need Sling Resource Merger patterns to work correctly):

Load reference: references/extending-core-components.md

When extending Core Components:

• Use @Self @Via(type = ResourceSuperType.class) for model delegation
• Implement ComponentExporter interface
• Add resourceType to @Model annotation
• Use sling:hideResource in dialog for inherited tabs/fields

Note: If the parent component is a project component (not a Core Component), use direct Java class extension (extends ParentModel) instead of the delegation pattern. The @Self @Via(type = ResourceSuperType.class) pattern is only for Core Components. Load references/extending-core-components.md for the decision table.

Step 2: Gather Requirements

2.1 Parse Dialog Specification

Echo back EXACTLY what you understood before creating:

Dialog Specification Confirmed:
I will create exactly {N} fields:
| # | Field Label | Field Type | Property Name |
|---|-------------|------------|---------------|
| 1 | {label1}    | {type1}    | {name1}       |
No additional fields will be added.
Is this correct?

2.2 Mockup Image Handling

• Both mockup AND spec provided: Dialog spec takes precedence. Mockup for HTML/CSS only.
• Only mockup provided: Propose fields and ASK for confirmation.

2.3 Figma Design Input

Load: references/figma-design-rules.md

When user provides a Figma URL (figma.com/design/..., figma.com/make/..., or figma.com/board/...):

1. Parse the URL to extract fileKey and nodeId (see references/figma-design-rules.md Rule 1)

• Convert - to : in the node-id query parameter
• Use branchKey as fileKey for branch URLs

1. **Call **get_design_context via the plugin-figma-figma MCP server (see Rule 2):{ "server": "plugin-figma-figma", "toolName": "get_design_context", "arguments": { "nodeId": "<extracted-node-id>", "fileKey": "<extracted-file-key>", "clientLanguages": "html,css,javascript", "clientFrameworks": "htl" } }
2. Extract design tokens from the response — colors, fonts, sizes, spacing, layout (see Rules 3-4)
3. Use the Figma output for HTL structure, CSS styling, and JS behavior — NOT for dialog fields

Precedence when BOTH dialog spec AND Figma URL are provided:

• Dialog specification → determines dialog fields (absolute precedence, no hallucination)
• Figma design → determines HTML structure, CSS styling, JS behavior only

When ONLY Figma URL is provided (no dialog spec):

• Analyze the design and PROPOSE dialog fields to the user
• ASK for confirmation before proceeding

Figma response handling:

• The response is React+Tailwind — treat as a REFERENCE, not production code
• Convert JSX to semantic HTL with BEM classes (see Rule 5)
• Extract all CSS values to the component clientlib (see Rule 6)
• Create JS only if interactivity is implied (see Rule 7)
• Do not hardcode Figma temporary image URLs — they expire and will break in production (see Rule 8)

2.4 Dynamic Content Requirements

Step 3: Create Component Files

Create ALL files in this order:

3.1 Component Definition

Path: ui.apps/src/main/content/jcr_root/apps/[project]/components/{component-name}/.content.xml

Load: references/aem-conventions.md

3.2 Component Dialog

Path: ui.apps/.../components/{component-name}/_cq_dialog/.content.xml

Load: references/dialog-patterns.md

For extended components: Load references/extending-core-components.md — Sling Resource Merger is required here because dialog inheritance only works through the merger; without it, parent dialog nodes won't be resolved.

3.2.1 Image Field Handling

When a user specifies an image or photo field:

• Default approach: Embed the Core Image component via data-sly-resource — do NOT create a fileupload dialog field with manual <img> rendering.
• Fileupload is only for non-image files (PDFs, documents, etc.). Only use cq/gui/components/authoring/dialog/fileupload when the user explicitly asks for a non-image file upload.
• Load references/htl-patterns.md (Image Handling section) for the correct embedding pattern.

3.3 HTL Template

Path: ui.apps/.../components/{component-name}/{component-name}.html

Load: references/htl-patterns.mdIf Figma URL provided, ALSO load: references/figma-design-rules.md (Rules 5, 8) — Convert JSX structure to semantic HTL with BEM classes. Replace static text with Sling Model expressions. Use the Figma screenshot as visual truth for element hierarchy.

i18n check: If the component has static display text (labels, button text, placeholder strings), use HTL i18n expressions: ${'Label Text' @ i18n}. Do not handle static text translation in the Sling Model — keep it in HTL where translation is automatic.

3.4 Sling Model

Path: core/src/main/java/[package-path]/models/{ComponentName}Model.java

Load: references/model-patterns.md, references/java-standards.md

For extensions: Load references/extending-core-components.md

Delegation Pattern (for Core Component extensions):

@Model(adaptables = SlingHttpServletRequest.class,
       adapters = {CustomModel.class, ComponentExporter.class},
       resourceType = CustomModel.RESOURCE_TYPE)
@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME,
          extensions = ExporterConstants.SLING_MODEL_EXTENSION)
public class CustomModel implements ComponentExporter {
    @Self @Via(type = ResourceSuperType.class)
    private com.adobe.cq.wcm.core.components.models.List coreList;
    // Use FQN for core interfaces to avoid import collision
}

3.5 Child Item Model - If Multifield

Path: core/src/main/java/[package-path]/models/{ItemName}.java

3.6 Unit Test

Path: core/src/test/java/[package-path]/models/{ComponentName}ModelTest.java

Load: references/test-patterns.md

3.7 Component Clientlib — Create for Every Component

Path: ui.apps/.../clientlibs/clientlib-{component-name}/

Load: references/clientlib-patterns.mdIf Figma URL provided, ALSO load: references/figma-design-rules.md (Rules 6, 7) — Extract exact colors, fonts, sizes, spacing, border-radius from the Figma response. Place all CSS into css/{component-name}.css using BEM naming. Create JS in js/{component-name}.js only if the design implies interactivity. Verify pixel-perfect fidelity against the Figma screenshot.

3.8 Dialog Clientlib - If Conditional Logic

Path: ui.apps/.../clientlibs/clientlib-{component-name}-dialog/

Load: references/clientlib-patterns.md (Dialog JavaScript Pattern section)

3.9 Sling Servlet - If Dynamic Content

Path: core/src/main/java/[package-path]/servlets/{ComponentName}Servlet.java

Load: references/sling-servlet-standards.md

3.10 Servlet Unit Test

Path: core/src/test/java/[package-path]/servlets/{ComponentName}ServletTest.java

3.11 Dependency Verification — Required for Servlets

Before completing, verify dependencies in core/pom.xml:

• Do not hardcode versions — check parent pom.xml for version properties instead, since hardcoded versions drift out of sync and cause build conflicts
• Most common APIs included in aem-sdk-api (GSON, Jackson, Commons)
• Use provided scope for AEM runtime libraries

Step 4: Completion Summary

Component '{component-name}' created successfully!

## Files Created
- ui.apps/.../components/{component-name}/.content.xml
- ui.apps/.../components/{component-name}/_cq_dialog/.content.xml
- ui.apps/.../components/{component-name}/{component-name}.html
- core/.../models/{ComponentName}Model.java
- core/.../models/{ComponentName}ModelTest.java
- ui.apps/.../clientlibs/clientlib-{component-name}/
[+ servlet files if applicable]

## Dialog Fields (Exact Match)
{table matching specification}

Would you like me to add any additional fields or build the project?

Quick Reference: Field Type Mapping

For complete mappings: assets/field-type-mappings.md

Reference Files

Load on-demand based on what you're creating:

If encountering issues during or after component creation, consult references/troubleshooting.md for common problems and solutions.