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:

Review the AI-assisted development tutorials for additional, hands-on instruction.

Feel free to email aemcs-ai-ide-tools-feedback@adobe.com with feedback to help shape product development.

AGENTS.md agentsmd

AGENTS.md is a markdown file at the root of your AEM project. AI coding tools load this file 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 of this document. 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:

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. See the Set up AEM Agent Skills tutorial for a concrete walkthrough.

Claude Code claude-code

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

# 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/main/skills/aem/cloud-service --all

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

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

# Install all available skills
gh upskill adobe/skills --path plugins/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 as a 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, and asks you to confirm the detected values. It 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. The design can come from various sources, including a text description, an image, or a Figma design url using Figma’s MCP server.

Learn more by following the Component development using AEM Agent Skills tutorial.

Use the Migration Skill use-the-migration-skill

The migration skill guides the agent through migrating AEM Java code and OSGi configurations to AEM as a Cloud Service. It works one pattern at a time: you name the pattern (for example, scheduler or replication), point the agent at your Best Practices Analyzer findings, and it locates the affected files in your project and applies the correct transformations in batches, pausing for your review after each one.

Supported patterns include Sling Scheduler, ResourceChangeListener, Replication API, OSGi EventListener and EventHandler, Assets API, HTL lint fixes, and OSGi config conversion with Cloud Manager secrets and environment variable extraction.

The skill pairs with the Cloud Migration MCP to fetch findings directly from Cloud Acceleration Manager. Without the MCP configured, the skill falls back to a local BPA CSV export, or you can point it at specific files manually.

For full setup instructions and pattern reference, see AI-Assisted Code Migration to AEM as a Cloud Service.

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 in the following section, provides the seven validation and runtime tools the skill uses when it needs local evidence.

Use the Code-assessment Skill (Beta) use-the-code-assessment-skill

This feature is beta. Adobe encourages you to provide feedback by emailing aemcs-ai-ide-tools-feedback@adobe.com to shape product development.

Beta releases may contain defects and are provided “AS IS” without warranty of any kind. Adobe has no obligation to maintain, correct, update, change, modify or otherwise support (by way of Adobe Support Services or otherwise) the beta releases. Adobe advises customers to use caution and not rely on the correct functioning or performance of beta releases, or on any accompanying documentation or materials. Features and APIs in beta are subject to change without notice. Accordingly, any use of the beta releases is entirely at the customer’s own risk.

The code-assessment skill detects, reviews, and fixes code-quality and correctness issues in an AEM as a Cloud Service project entirely within your local workspace. Describe the issue, and the skill routes the request to the appropriate remediation workflow.

Supported checks include modernizing Sling Model dependency injection, updating outdated Maven dependencies, adding missing timeouts to outbound HTTP calls, bounding unbounded queries, Sling schedulers, resource change listeners, the Replication and Assets APIs, and JCR or OSGi event handling, plus scanning and fixing usage of deprecated and removed AEM APIs, with more added over time. Depending on the issue, the skill either applies a mechanical fix directly or guides you through one that needs a judgment call.

For a broad or first-time review, ask the skill to assess the whole project: it runs every detector, reports all findings, and applies code fixes one pattern at a time.

To get started, open a new agent chat in your AEM as a Cloud Service project.

1. Review your project. Ask for a report. The skill runs its analyzer and returns the findings inline, grouped by pattern and severity, with a suggested remediation plan. No code is changed at this stage.

scan my AEM project and report any code-quality issues

For a more explicit invocation, name the skill directly:

/code-assessment review my code for AEM as a Cloud Service issues

To focus on a single pattern, name it in the prompt:

scan my project for unbounded queries

2. Apply fixes, one pattern at a time. Ask the skill to fix a specific pattern. It makes surgical edits and verifies they compile. Mechanical fixes apply directly; guided ones walk you through each decision.

apply unbounded-query

It never commits or pushes — you review the diff and commit. Large fixes run in resumable batches; reply apply <pattern> to continue.

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.