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?

Status	Action
File missing or configured: false	Stop and display the error message below. Do not explore the codebase or proceed — the config values are needed for correct file paths and naming. Wait for the user to configure.
configured: true	Read project, package, and group values from the YAML file. Proceed with component creation.

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	Action
0	Configuration validation (do this first — see above)
1	Extract & validate component name
1.5	Component extension decision (if extending)
2	Gather requirements & confirm dialog specification
2.3	Figma design fetch (if Figma URL provided)
3	Create all component files
3.11	Dependency verification (required for servlets)
4	Completion summary

Step 0: Configuration Validation

0.1 Read Configuration

Read .aem-skills-config.yaml from the project root
Check that configured: true
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

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

0.4 Project State Analysis (after configuration validated)

Check Component Name Uniqueness - Look in /apps/[project]/components/
Check Model Class Conflicts - Look in core/src/main/java/[package-path]/models/
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

User Says	Maps To
image	core/wcm/components/image/v3/image
teaser, card	core/wcm/components/teaser/v2/teaser
text, richtext	core/wcm/components/text/v2/text
title, heading	core/wcm/components/title/v3/title
list	core/wcm/components/list/v4/list
button, cta	core/wcm/components/button/v2/button
navigation, nav	core/wcm/components/navigation/v2/navigation
container, section	core/wcm/components/container/v1/container
accordion	core/wcm/components/accordion/v1/accordion
tabs	core/wcm/components/tabs/v1/tabs
carousel	core/wcm/components/carousel/v1/carousel
embed, video	core/wcm/components/embed/v2/embed

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

User Request	Action
"Add custom fields"	Create new tab OR add to existing
"Hide {tab}"	Use sling:hideResource="{Boolean}true"
"Hide {field}"	Use sling:hideResource="{Boolean}true"
"Override {field}"	Use sling:hideProperties + new values

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/...):

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

**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" } }
Extract design tokens from the response — colors, fonts, sizes, spacing, layout (see Rules 3-4)
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

User Indicates	Servlet Required?
External API integration	Yes (GET)
Dynamic data loading	Yes (GET)
Form submission	Yes (POST)
Search/filter	Yes (GET)
Static dialog content	No

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

User Says	Granite Resource Type
Textfield	granite/ui/components/coral/foundation/form/textfield
Textarea	granite/ui/components/coral/foundation/form/textarea
Richtext, RTE	cq/gui/components/authoring/dialog/richtext
Pathfield, Path	granite/ui/components/coral/foundation/form/pathfield
Image, Photo	Embed Core Image component (see references/htl-patterns.md Image Handling section). Do not use fileupload for image rendering.
Fileupload, File Upload	cq/gui/components/authoring/dialog/fileupload (for non-image files: PDFs, documents)
Multifield	granite/ui/components/coral/foundation/form/multifield
Checkbox	granite/ui/components/coral/foundation/form/checkbox
Select, Dropdown	granite/ui/components/coral/foundation/form/select
Numberfield	granite/ui/components/coral/foundation/form/numberfield
Datepicker	granite/ui/components/coral/foundation/form/datepicker

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

Reference Files

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

Creating	Load Reference
Any component	.aem-skills-config.yaml (project root, load first — see Configuration Gate Check), then references/aem-conventions.md
Dialog XML	references/dialog-patterns.md
HTL Template	references/htl-patterns.md
Sling Model	references/model-patterns.md, references/java-standards.md
Unit Tests	references/test-patterns.md
Clientlibs	references/clientlib-patterns.md
Extending Core Component	references/extending-core-components.md
Extending Core Component — worked example & checklists	references/extending-core-components-example.md (load when you need a complete worked example of extending a Core Component, unit testing patterns, or the implementation checklist)
Sling Servlet	references/sling-servlet-standards.md
Core Component patterns	references/core-components.md
No Hallucination rules	references/no-hallucination-rules.md
Figma design integration	references/figma-design-rules.md
Troubleshooting	references/troubleshooting.md
Examples	references/examples.md

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

create-component