Developing with AI Tools

AI coding tools such as Claude Code, Cursor, Codex, Gemini, GitHub Copilot, or Zed and the models they employ generally have good working knowledge of the core technologies that power AEM. As we use semantic HTML, Vanilla JavaScript, and framework-less CSS, we benefit from the largest possible training set.

While there are some specific ways we use those technologies, much of that can be inferred from your project codebase (e.g. aem.js), allowing developers to use AI coding agents effectively without specialized tooling.

This guide is intended to cover ways you can enhance that experience to get the most out of these tools and to make your AEM “vibe coding” sessions as productive as possible.

Helping the Agents Search

Modern coding agents have access to web search, but they will often mix up the Java/JCR/OSGi-based technology stack for AEM Sites as a Cloud Service with the lightweight HTML/CSS/JavaScript stack of Edge Delivery Services in Adobe Experience Manager Sites as a Cloud Service when you ask about AEM. When asking about Edge Delivery Services, you often get information about Cloudflare's, Akamai's or Fastly's Edge Compute and CDN infrastructure, and searching for EDS will bring up medical information.

The best way to prevent that is to specify "search the www.aem.live website".

Without Context

> Help me find information about EDS.

⏺ I'll help you find information about EDS. Let me search for relevant
  information.

⏺ Web Search("EDS Ehlers-Danlos Syndrome medical condition information")

╭─────────────────────────────────────────────────────────────────────────────────╮
│ Tool use                                                                        │
│                                                                                 │
│   Web Search("EDS Ehlers-Danlos Syndrome medical condition information")        │
│   Claude wants to search the web for: EDS Ehlers-Danlos Syndrome medical        │
│   condition information                                                         │
│                                                                                 │
│ Do you want to proceed?                                                         │
│ ❯ 1. Yes                                                                        │
│  2. Yes, and don't ask again for Web Search commands in                         │
│  /private/tmp/new-project                                                       │
│   3. No, and tell Claude what to do differently (esc)                           │
│                                                                                 │
╰─────────────────────────────────────────────────────────────────────────────────╯

With Context

> Help me find information about Edge Delivery. Search www.aem.live

⏺ I'll help you search for information about Edge Delivery on
  http://www.aem.live.

⏺ Fetch(https://www.aem.live)
  ⎿  Fetching…

╭─────────────────────────────────────────────────────────────────────────────────╮
│ Fetch                                                                           │
│                                                                                 │
│   https://www.aem.live                                                          │
│   Claude wants to fetch content from www.aem.live                               │
│                                                                                 │
│ Do you want to allow Claude to fetch this content?                              │
│ ❯ 1. Yes                                                                        │
│   2. Yes, and don't ask again for www.aem.live                                  │
│   3. No, and tell Claude what to do differently (esc)                           │
│                                                                                 │
╰─────────────────────────────────────────────────────────────────────────────────╯

Establishing Context

We publish an llms.txt file which provides an overview of AEM and links to key documentation in a format optimized for AI consumption. Most agents don't refer to it proactively, but mentioning this file in a rules file or your prompt allows the agent to quickly include key documentation and APIs in its context to produce better results. Many tools also allow you to index custom documentation, in which case you should add http://www.aem.live/docs/.

You should also consider adding an AGENTS.md to your project. Note that Claude Code refers to this file as CLAUDE.md so you may want both for maximum compatibility. You can use this AEM Boilerplate example as a starting point, but don’t be shy about adjusting it to fit your specific project.

Helping the Agents see

In many cases, your coding agent will make assumptions about what your site looks like without having the ability to actually verify this. You can help the agent in multiple ways:

By taking screenshots of the page rendered on localhost:3000 and adding them to the chat
By installing Puppeteer or Playwright and encouraging the agent to write small ad-hoc scripts to verify functionality
By installing specialized Model Context Protocol servers (see below)

Giving Agents Skills

Skills are specialized, reusable workflows that help your AI coding agent perform complex, multi-step tasks more effectively. Think of them as mini-playbooks that bundle together instructions, reference materials, and scripts to handle specific scenarios.

Skills use progressive disclosure to load detailed instructions only when needed, preserving your agent's context window for what matters.

While skills are a Claude Code native feature, other agents can leverage the same skills through guidance in your project’s AGENTS.md file. For more details on Claude Code's skill system, see the Claude Code documentation.

AEM Skills

For developing this site we use a set of skills that help agents tackle development, testing, and migration tasks according to AEM best practices. These skills follow three main patterns that work together:

Orchestration Skills - Entry point skills that coordinate complete workflows from start to finish. These are the skills agents start with when tackling major tasks

Content Driven Development - Orchestrates the complete development workflow for building or modifying blocks and codifies AEM's content-first philosophy by requiring test content before code
Page Import - Orchestrates the complete import workflow for migrating webpages to AEM Edge Delivery Services. Used when bringing existing pages into AEM

Functional Skills - Specialized skills invoked by orchestrators (or used directly) for specific sub-tasks like implementation, testing, or content modeling.

Building Blocks - Provides JavaScript decoration patterns, CSS styling conventions, and AEM-specific best practices for creating or modifying blocks
Content Modeling - Guides agents to design effective initial content structures (the author-developer contract) that make blocks intuitive for authors to use

Research Skills - Standalone skills that help agents find information, references, or understand what's available.

Docs Search - Searches aem.live documentation and blogs for platform feature information, implementation guidance, and best practices
Block Inventory - Surveys available blocks from the local project and Block Collection to understand what's already built

Adding Skills to Your Project

The easiest way to add skills is using gh-upskill

# Install gh-upskill as a GitHub CLI extension
gh extension install trieloff/gh-upskill

# Add AEM skills to your project (run from project root)
gh upskill adobe/helix-website

This adds the skills we use to your project's .claude/skills/ directory as well as a skill discovery script and instructions on using skills to AGENTS.md.

Using Skills

Once added, skills are automatically usable. Just prompt as you normally would and your agent should apply the skills where appropriate. General prompt engineering guidance still applies, so you should, for example, mention a specific skill when you know you want the agent to use it.

💡Pro-tip: If you notice your agent going off-course, or not applying the skills correctly, you can ask the agent to update the skills to avoid repeating the same mistakes.

Sample prompts

Build an embed block for instagram urls
Update the CSS of the hero block to match this style (add screenshot)

Useful Tools for AI Agents

The best AI agents have received massive reinforcement learning on using a set of command line tools that can speed up their development workflow, but which you often don't have pre-installed on your system. Consider installing them, so that your AI agent has more capable tools at their disposal.

ripgrep (rg) - Fast text search across codebase
jq - JSON processor and transformer
gh - GitHub CLI
curl - Command-line HTTP requests
ast-grep (sg) - Syntax-aware code search and transformation
httpie - Human-friendly HTTP client
fzf - Fuzzy finder for interactive file/command selection
fd - Fast and user-friendly alternative to find
bat - Syntax-highlighted cat replacement with Git integration

Ask your AI agent if they are installed on your machine and tell them to install if not.

Request Reviews from AI

The AEM development flow is centered around GitHub and Pull Requests. This makes it an excellent match for AI code reviews that work both for humans and AI-generated pull requests (don't worry, AI code reviewers don't give other AIs a free LGTM-pass).

GitHub Copilot Code Reviews do not require any setup
Claude Code Pull Request Reviews are based on GitHub Actions
OpenAI Codex Code Review offers pull request reviews through a dedicated GitHub app

Model Context Protocol

The Model Context Protocol (MCP) provides extensibility for AI agents and almost all AI agents support it. You can try these MCP tools that work well with AEM. Remember that MCP tools will fill up the available context window, so you should disable tools that you do not use.

> /context
  ⎿
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛀ ⛀
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   Context Usage
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   claude-sonnet-4-20250514 • 17k/200k tokens (8%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 3.0k tokens (1.5%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 11.4k tokens (5.7%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 1.3k tokens (0.7%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 705 tokens (0.4%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 91 tokens (0.0%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛶ Free space: 183.4k (91.7%)

     MCP tools · /mcp
     └ mcp__context7__resolve-library-id (context7): 691 tokens
     └ mcp__context7__get-library-docs (context7): 652 tokens

     Memory files · /memory
     └ User (/Users/trieloff/.claude/CLAUDE.md): 705 tokens