AEM Developer AI Context Kit: AGENTS.md, Skills & Prompt Library
[OVERVIEW]
I built a five-layer context system to stop AI coding assistants from guessing their way through AEM work. Copilot, Claude Code, Cursor - they're all capable, but without knowing how a specific project is put together they fall back on generic training data, and you end up reworking half of what they produce in review. So instead of repeating context in every prompt, I layered it: an AGENTS.md file at the repo root (generated with Adobe's ensure-agents-md skill via npx skills --plugin github-copilot) covering the project's purpose, structure, and build/test commands; smaller scoped instruction files for specific concerns, like .agents/instructions/testing.junit5.md for test conventions; Adobe's own vendor skills (Cloud Service, 6.5 LTS, or EDS depending on the project) for baseline best practices around components, dispatcher config, and OSGi; custom skills for the corrections I found myself making over and over; and a shared, versioned prompt library so the team isn't reinventing prompts every time. Once those layers exist, the prompts themselves get a lot shorter.
[IMPACT]
The goal was simple: cut the rework cycle on AI-assisted AEM code and get the team prompting consistently instead of everyone winging it their own way. With the context layers in place, the assistant starts from AEM best practices instead of a guess, so there's less to fix in the dialog/HTL/Sling Model output. Once something's encoded as a skill, I stop having to correct it again. And prompts get noticeably shorter and more reliable once AGENTS.md and the skills are doing the heavy lifting.
[LESSONS]
Biggest lesson: the assistant is a fast pair of hands, not a judgement call - it doesn't know your situation, so the context layer gives it knowledge and the prompt gives it direction, but the actual architecture decisions stay with you. A few things that made a real difference: give it the contract up front (expected dialog fields, Sling Model properties, HTL structure) before asking for code; ask for tests before a refactor so you've got something to anchor the change against; call out a skill by name when a specific approach matters; keep changes small and reviewable rather than asking for everything at once.
Gotchas I ran into: don't trust OSGi config or service lifecycle code it generates from memory, check it; don't take dispatcher rules at face value, validate them (the Dispatcher MCP server is handy for this); don't assume Sling resource type resolution just works without testing it; treat AEM migrations as a first draft, not a finished job.
[TRYABLE]
1. Install Adobe's open-source skills for your AI tool: npx skills --plugin github-copilot (swap the plugin for cloud-service, aem-65, or edge-delivery-services depending on what you're targeting).
2. Run the ensure-agents-md skill to generate AGENTS.md at the repo root. Review it - it should cover the project's purpose, module layout, and build/test commands - then commit it.
3. Add scoped instruction files under .agents/instructions/ for anything that needs its own rules, e.g. testing.junit5.md for test conventions, and reference them from AGENTS.md's Conventions section.
4. Let the installed vendor skills handle the baseline: component creation (dialog, HTL, Sling Model, tests, clientlibs together), dispatcher config, OSGi patterns, and migration tasks.
5. Watch code review. Anything you correct more than once is a candidate for a custom skill - write it and commit it to .agents/skills/ so it becomes the default for the whole team.
6. Build out a shared, versioned prompt library for recurring tasks. Since AGENTS.md and the skills now carry the context, prompts can stay short - just state intent.
7. Optionally wire in MCP servers: the Quickstart MCP Server for reading logs and diagnosing OSGi bundles, and the Dispatcher MCP Server for validating dispatcher config and cache behaviour instead of trusting generated rules.
8. When prompting: give the contract first (expected dialog fields, Sling Model properties, HTL) before asking for code, ask for tests before a refactor, name a skill explicitly when a specific approach matters, and work in small increments you can review.
[SETUP]
Node.js/npx to install and run the skills packages. Write access to the repo to commit AGENTS.md, .agents/instructions/, and .agents/skills/. An AI coding assistant that supports the Agent Skills spec (GitHub Copilot, Claude Code, or Cursor). A local AEM SDK instance if you want to use the Quickstart MCP Server. Dispatcher config access if you're using the Dispatcher MCP Server.
[SAMPLE_OUTPUT]
Adobe's open-source skills repo (install via npx skills): https://github.com/adobe/skills
Downloadable prompt library template: https://experienceleague.adobe.com/content/dam/exlm/en/resources/adobe-experience-manager/an-aem-developers-guide-to-agents-md-skills-and-prompt-libraries/Prompt%20Library%20-%20AEM%20development.docx