Local Development with AI Tools local-development-with-ai-tools

AI coding agents (Claude Code, Cursor, GitHub Copilot, and similar tools) have broad knowledge of AEM’s underlying technologies (Java, OSGi, Sling, JCR, HTL) but don’t necessarily know best practices for generating code and configuration, or how to debug common AEM development issues.

Four complementary components address this:

AGENTS.md agentsmd

AGENTS.md is a Markdown file at the root of your AEM project that AI coding tools load automatically at the start of every session in order to be grounded with essential AEM Cloud Service Java-stack domain expertise (and not other AEM solutions such as AEM 6.5 or Edge Delivery Services).

AGENTS.md is not a static file you copy — it is generated by the ensure-agents-md skill described in the next section. The skill reads your pom.xml to resolve the project name, discover modules, and detect installed add-ons, producing a file tailored to your specific project.

Agent Skills agent-skills

Skills are instruction sets that encode multi-step development workflows. When invoked, the AI follows the skill’s procedure rather than relying solely on general knowledge, producing consistent, convention-compliant results.

Adobe publishes AEM as a Cloud Service skills in the adobe/skills repository on the beta branch since this feature is not yet generally available:

Install Skills install-skills

Choose the method that matches your AI coding tool. Installing skills once makes them available for all projects on that machine.

Claude Code claude-code

# Add the Adobe Skills marketplace (one-time setup)
/plugin marketplace add adobe/skills#beta

# Install all available skills
/plugin install aem-cloud-service@adobe-skills

Npx Skills npx-skills

# Install all available skills
npx skills add https://github.com/adobe/skills/tree/beta/skills/aem/cloud-service --all

Upskill (GitHub CLI extension) upskill-github-cli-extension

# Install the gh-upskill extension (one-time setup)
gh extension install trieloff/gh-upskill

# Install all available skills
gh upskill adobe/skills --branch beta --path skills/aem/cloud-service --all

Use the ensure-agents-md Skill use-the-ensure-agents-md-skill

After installing the skill, open your AI assistant in any AEM Cloud Service project that does not yet have an AGENTS.md. The skill runs automatically before processing your first request, creating both files at the project root without requiring explicit invocation.

Use the create-component Skill use-the-create-component-skill

On first use, the skill automatically detects project, package, and group from pom.xml and existing components, asks you to confirm the detected values, then creates .aem-skills-config.yaml at the project root. No manual configuration is required before first use.

If you prefer to pre-create the file, place .aem-skills-config.yaml at the project root with the following structure:

configured: true

project: "wknd"                                    # Check /apps/{project}/ or pom.xml
package: "com.adobe.aem.guides.wknd.core"          # Check core/pom.xml
group: "WKND Components"                           # Check existing component .content.xml files

The file lives outside the skill directory and is never overwritten when the skill is updated.

Describe the component in your AI chat:

Create an AEM component called "Hero Banner"

Dialog specification:
Title (title) - Textfield, mandatory
Subtitle (subtitle) - Textfield
Background Image (backgroundImage) - Fileupload
CTA Text (ctaText) - Textfield
CTA Link (ctaLink) - Pathfield

The agent echoes the field specification for confirmation, then generates all component files. Supported patterns include multifield with composite nested items, conditional show/hide logic, Core Component extension via Sling Resource Merger, and JUnit 5 tests using AEM Mocks.

Use the Dispatcher Skill use-the-dispatcher-skill

Invoke the dispatcher skill for any Dispatcher or Apache HTTPD configuration work. The skill routes requests to one of six specialist sub-skills depending on the nature of the request:

For broad or first-time requests, start with the workflow-orchestrator sub-skill. For targeted work, describe the specific concern and the skill routes to the appropriate specialist.

The dispatcher skill handles orchestration and advisory guidance. The Dispatcher MCP server, described below, provides the seven validation and runtime tools the skill uses when it needs local evidence.

AEM Quickstart MCP Server aem-quickstart-mcp-server

The Model Context Protocol (MCP) is an open standard that allows AI coding tools to connect to external data sources and services. The AEM Quickstart MCP server is a content package that, once installed in a local AEM SDK instance, exposes runtime data directly to connected AI tools — enabling agents to retrieve logs, diagnose OSGi failures, and inspect request processing without leaving the IDE.

Install the Content Package install-the-content-package

Download the content package from the Software Distribution Portal and install com.adobe.aem:com.adobe.aem.mcp-server-contribs-content into your local Quickstart using Package Manager at /crx/packmgr.

Compatibility: Validated with AEM SDK 2026.2.24678.20260226T154829Z-260200 and newer.

Available Tools available-tools

Configure Your IDE configure-your-ide

Cursor cursor

In Cursor Settings, add a new custom MCP server:

"aem-cs-sdk": {
  "type": "streamable-http",
  "url": "http://localhost:4502/bin/mcp",
  "headers": {
    "Authorization": "Basic YWRtaW46YWRtaW4="
  }
}

GitHub Copilot with IntelliJ IDEA github-copilot-with-ihtellij-idea

Navigate to Tools > GitHub Copilot > Model Context Protocol (MCP) and click Configure. Add:

"aem-cs-sdk": {
  "url": "http://localhost:4502/bin/mcp",
  "requestInit": {
    "headers": {
      "Authorization": "Basic YWRtaW46YWRtaW4="
    }
  }
}

Other IDEs other-ides

Any MCP client can connect by pointing to http://localhost:4502/bin/mcp with an Authorization: Basic YWRtaW46YWRtaW4= header. Configure custom headers using your IDE’s MCP settings.

Dispatcher MCP Server dispatcher-mcp-server

The Dispatcher MCP server is bundled with the AEM Dispatcher SDK. It enables AI tools to validate Dispatcher and Apache HTTPD configuration, trace request handling, and inspect cache behavior against a Dispatcher instance running locally in Docker.

Unlike the dispatcher skill, the Dispatcher MCP server exposes tools only: seven MCP tools and no prompts or resources.

Prerequisites prerequisites

Install the Dispatcher SDK install-the-dispatcher-sdk

macOS and Linux:

chmod +x aem-sdk-dispatcher-tools-<version>-unix.sh
./aem-sdk-dispatcher-tools-<version>-unix.sh
cd dispatcher-sdk-<version>
chmod +x ./bin/docker_run_mcp.sh
./bin/docker_run_mcp.sh test

Windows:

Expand-Archive aem-sdk-dispatcher-tools-<version>-windows.zip

Run ./bin/docker_run_mcp.sh help to retrieve copy-paste IDE configuration and ./bin/docker_run_mcp.sh version to confirm the bundled MCP and SDK version. Use ./bin/docker_run_mcp.sh diagnose to investigate connectivity issues.

Configure Cursor configure-cursor

Add an aem-dispatcher-mcp entry to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "aem-dispatcher-mcp": {
      "command": "<path_to_dispatcher_sdk>/bin/docker_run_mcp.sh",
      "env": {
        "DOCKER_API_VERSION": "1.43",
        "AEM_DEPLOYMENT_MODE": "cloud",
        "MCP_LOG_LEVEL": "trace",
        "MCP_LOG_FILE": "/tmp/dispatcher-mcp.log",
        "DISPATCHER_CONFIG_PATH": "<path_to_dispatcher_src>"
      }
    }
  }
}

Replace <path_to_dispatcher_sdk> with the extracted Dispatcher SDK location and <path_to_dispatcher_src> with the project’s dispatcher src directory. Set DISPATCHER_CONFIG_PATH to the config root that includes the files where /docroot is defined. MCP_LOG_LEVEL and MCP_LOG_FILE are optional debugging settings. If you see client version 1.43 is too new, set DOCKER_API_VERSION to 1.41. If other MCP servers are already configured, add the aem-dispatcher-mcp entry without replacing them. Restart Cursor after saving.

Other IDEs can be configured in a similar manner. The SDK’s docs/DispatcherMCP.md includes complete examples for Claude Desktop and VS Code.

Available Tools available-tools-dispatcher

The MCP surface intentionally exposes only these seven tools; prompts and resources remain in the skill layer. Full reference documentation is available in docs/DispatcherMCP.md inside the extracted Dispatcher SDK.