feat(aem-cloud-service): add aem-agentkit skill for agentic workflow bootstrap (beta)

[abhishekgarg18]

Summary

Adds aem-agentkit (beta) — a skill that bootstraps an AEM as a Cloud Service repository for agentic workflows across Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Continue.dev, Cline, Windsurf, Augment, Aider, and every other AGENTS.md-spec-compliant agent — without modifying any customer source code.

It complements (does not replace) ensure-agents-md, which customers already follow per Adobe Experience League's Set up AEM Agent Skills docs. ensure-agents-md continues to own root AGENTS.md + CLAUDE.md. aem-agentkit adds everything else.

Why this skill exists

Coding agents work best when the repository ships machine-readable context they can query before generating code. Without it, each turn re-derives the same answers from scratch: "What's the build command? Where do components live? What's the Sling Model annotation style? Does this component already exist?" Agents that re-derive on every turn produce duplicate components, hallucinated class names, drift from house style, and break Cloud Service constraints they don't know about.

aem-agentkit answers those questions once, in a stable place, so every agent turn starts informed. The customer needs to do exactly one thing after the skill runs: wire MCP servers. Everything else ships ready.

Hard guarantees

• Customer source files are never modified. The skill writes only into an allow-list of agent-meta paths. git status before vs after the run shows zero modifications to any pre-existing tracked or untracked file. Only new files appear.
• Never modifies the root AGENTS.md or CLAUDE.md owned by ensure-agents-md.
• Idempotent + non-destructive across versions. Marker-based: a file lacking the marker is human-curated and never touched. A marker-bearing file with drifted content goes to <path>.agentkit-new; the original is preserved.
• Stub-over-hallucinate. Every derived rule cites at least 3 evidence pointers (file:line) or becomes a TODO marker the customer reviews.
• Privacy deny-list. Never reads .env*, .cloudmanager/secrets*, **/credentials*, **/*creds*, **/*secret*, **/*.pem, **/*.key, **/*.p12, or anything inside .git/ besides top-of-tree state.
• Customer opt-out via a _disable_agentkit file at the workspace root — single empty file, exits the skill silently.
• Beta. Three independent markers per plugins/aem/cloud-service/CLAUDE.md: frontmatter metadata.status: beta, [BETA] description prefix, body blockquote.
• Atomic writes. Every output goes to <path>.tmp and is renamed to <path> on success. Orphan .tmp files from a previous interrupted run are cleaned at startup.
• Output stability. JSON sorted-keys + 2-space indent + LF + final newline + UTF-8 no BOM. Markdown LF + final newline + no trailing whitespace. Discovery enumerates with sorted directory listings so the same input produces byte-identical output across runs and platforms.
• No marketing language in any generated artifact. Framing uses agentic-workflow terminology only.

LLM-agnostic by design

Three coverage layers:

Layer	Tools
Universal layer (always written)	Read natively by every AGENTS.md-spec-compliant agent: OpenAI Codex, Gemini CLI, Zed, Factory, Jules, Devin, Amp, Kilo, RooCode, Warp, JetBrains Junie, Ona, Phoenix, Aider, and any future adopter
Per-glob/per-role projection (when signal detected)	Claude Code (.claude/), Cursor (.cursor/), GitHub Copilot (.github/), Continue.dev (.continue/)
Single-file rule projection (when signal detected)	Cline (.clinerules), Windsurf (.windsurfrules), Augment Code (augment.md)

The universal layer is the LLM-agnostic foundation. Tool-specific projections give each tool's native routing system (Claude subagents, Cursor .mdc globs, Copilot applyTo, Continue rules, Cline / Windsurf rule files) the same canonical content. A single canonical role-prompt source in references/templates/roles/ is projected into each tool's format so the body of every author role is byte-identical across IDEs; only the frontmatter and extension differ.

Customers using an agent we don't have a projection for still get the full universal layer, which is enough for AGENTS.md-spec-compliant agents to behave correctly.

Customer benefit per artifact

Universal layer (always written when missing)

Artifact	What the customer gets
<module>/AGENTS.md (recursive, including sub-projects)	Focused per-module context loaded only when the agent works in that module. Smaller context window load → more room for actual code → fewer mistakes. Nested AEM monorepos get leaf files at the right depth so context locality holds inside each sub-project's core/, ui.apps/, ui.frontend/, etc.
.aem/context/components.json	"Does Hero already exist?" answered with one read instead of grep + interpret across many files. Prevents duplicate components. Catches name collisions across component groups.
.aem/context/osgi-services.json	Same shape for Sling Models, OSGi services, Sling Servlets across every Java module. Surfaces DS R6 vs R7 so new services match house style.
.aem/context/conventions.md	Every derived rule cites 3+ evidence pointers with file:line precision: package naming, Sling Model annotation style, OSGi DS style, HTL naming, logging, dispatcher includes, build/verify command. Generated code matches the project's style on first try.
.aem/context/avoid.md	Anti-patterns detected in this repo's own code (Felix SCR usage, JCR observation EventListener, deprecated AssetManager ops, getAdministrativeResourceResolver, HTL data-sly-test redundant comparisons). Each entry points at the supported replacement in the existing best-practices skill. Stops agents re-suggesting patterns the team has decided to migrate away from.
.aem/context/glossary.md	Customer domain terms extracted from cq:title values, Content Fragment model titles, and taxonomy node names so the agent uses the project's vocabulary without asking.
.aem/context/test-patterns.md	How this project actually writes tests — JUnit version, AemContext extension, mocking framework, integration-client setup. New tests look like existing tests on first attempt.
.aem/context/aem-api-namespaces.md	Static reference of canonical AEM Cloud Service API package roots (com.adobe.aem.*, com.adobe.cq.*, com.adobe.granite.*, com.day.cq.*, org.apache.sling.*, OSGi DS R7 vs Felix SCR, SLF4J, JCR). Backs the "verify before import" guardrail. Reduces fabricated class names.
.aem/context/README.md	Human-readable index for newcomers and unfamiliar agents.

For nested AEM monorepos, the same set is written at each sub-project root (<sub-project>/.aem/context/), scoped to that sub-project only. Shared root index for cross-cutting queries; sub-project index for focused work.

Per-tool projections

Artifact	What the customer gets
aem-component-author role	Project-scoped component author — knows the index, honors house conventions, updates the index after writing code
aem-sling-model-author role	Sling Model author matching project annotation style with matching test
aem-htl-author role	HTL passing Cloud SDK lint on first try (no redundant data-sly-test, no inline styles, no /libs writes)
aem-dispatcher-editor role	Dispatcher edits respecting cloud vs legacy layout; SDK validation runs before declaring done
aem-osgi-config-author role	OSGi config authoring with runmode-folder conventions, PID validation against the index, env-var indirection for secrets
aem-integration-test-author role	it.tests author following the project's AEM Testing client setup, no admin credentials
aem-ui-test-author role	Cypress author using data-test-id selectors and intercept-based waits
aem-content-fragment-author role (conditional)	CF author using the project's discovered CF models
aem-guardrails rule	Always-on rule applying the search-before-create, verify-before-import, no-/libs-writes, stop-on-red, honor-the-indexes guardrails
/new-component slash command (Claude)	Single command: check duplicates → delegate to component-author → run the build → update the index
/new-sling-model slash command (Claude)	Model + test + index update in one command
/validate-dispatcher slash command (Claude)	One command runs the SDK validation, clean summary
/regen-context slash command (Claude)	Refresh codified context without remembering the skill name
/agents-md-check slash command (Claude)	Read-only drift report; useful as a manual quality gate before merge
.mcp.json / .cursor/mcp.json placeholders	Structured slot for AEM developer MCP, Cloud Manager MCP, Content MCP — customer fills in real server commands once

Operational artifacts

Artifact	What the customer gets
Marker comment on every file	grep -rlF "aem-agentkit: generated" . lists every generated file. Deletion = uninstall.
.agentkit-new diff-suffix files (on refresh)	The skill never overwrites hand-edited files. Drift goes to a .agentkit-new sibling; the customer chooses whether to swap. Refactors and version bumps are non-destructive.
_disable_agentkit opt-out	Customers who want the rest of the cloud-service plugin without this skill firing drop a single empty file. CI-friendly.
Schema versioning (_skillVersion + schemaVersion)	Forward-compatible upgrades. Old marker + older schemaVersion triggers migration to .agentkit-new; original preserved.

End-to-end coverage with public sibling skills

This skill covers the bootstrap phase. The other phases of an E2E agentic workflow on AEM as a Cloud Service are handled by sibling skills already published in the public adobe/skills repo under the same plugin:

Phase	Public sibling skill
Bootstrap (this skill)	aem-agentkit — per-module AGENTS.md, codified context, tool-specific routing
Root context	ensure-agents-md — root AGENTS.md + CLAUDE.md
Pattern transformation	best-practices — Cloud Service patterns, legacy-to-cloud transformations
Component scaffolding	create-component — opinionated component scaffolds
Migration orchestration	migration — BPA / CAM orchestration on top of best-practices
Workflow authoring	aem-workflow — Granite Workflow model design, development, triggering, debugging, triaging
Dispatcher	dispatcher — config authoring, advisory, incident response, performance tuning, security hardening
Content distribution	content-distribution — Sling distribution and replication
Rapid Development	aem-rde — RDE deploy, log inspection, snapshots, troubleshooting via aio aem rde

The bootstrap this skill writes is read by every later-phase skill. A customer who has installed the aem-cloud-service plugin (which bundles every skill above) and run aem-agentkit has end-to-end agentic-workflow coverage on their repository.

Detection and recursion

Silent IDE detection (no prompts)

Tool	Signal
Claude Code	.claude/ directory or CLAUDE.md at root
Cursor	.cursor/ directory
GitHub Copilot	.github/copilot-instructions.md or any .github/*.yml workflow
OpenAI Codex	always (reads AGENTS.md natively)
Continue.dev	.continue/ directory
Cline (VS Code)	.clinerules file or .vscode/extensions.json listing the Cline extension
Windsurf	.windsurfrules file or .codeium/ directory
Augment Code	.augment/ directory or augment.md at root
Aider, Gemini CLI, Zed, Factory, Jules, Devin, Amp, Kilo, RooCode, Warp, JetBrains Junie, Ona, Phoenix	always (read AGENTS.md natively)

Recursive monorepo support

When the root pom.xml's <modules> include themselves-full-AEM-archetypes (a module with its own pom declaring <modules> and 2+ archetype dirs core, ui.apps, ui.apps.structure, ui.config, ui.content, ui.frontend, all), the skill recurses (bounded to 3 levels):

• Writes a sub-project overview AGENTS.md at the nested AEM project root
• Writes per-archetype-leaf AGENTS.md at each leaf inside (<sub>/core/AGENTS.md, <sub>/ui.apps/AGENTS.md, etc.)
• Writes a sub-project-scoped .aem/context/ containing the same 8 files but scoped to that sub-project only

Git submodules at any level are out of scope — each is treated as an independent repo to be bootstrapped from its own root.

Custom-module heuristic

For top-level modules whose names don't match a standard archetype, the skill detects purpose from pom.xml content:

Signal	Inferred purpose	Template
maven-checkstyle-plugin / maven-enforcer-plugin as primary build goal	Code quality / enforcement	AGENTS.module.code-quality.md.template
frontend-maven-plugin + name matches *-frontend*	Custom frontend	AGENTS.module.ui.frontend.md.template (variant: custom)
<packaging>pom</packaging> with no archetype children	Analysis / scripting	AGENTS.module.analysis.md.template
Otherwise	Unknown	AGENTS.module.generic.md.template

What the customer needs to do after this skill runs

Wire MCP servers. That is the only remaining step.

.mcp.json ships with commented placeholder entries for AEM developer MCP, Cloud Manager MCP, and Content MCP. The customer replaces the REPLACE_WITH_*_COMMAND stubs with their real server commands. Same for .cursor/mcp.json if they use Cursor.

Everything else — root AGENTS.md (via ensure-agents-md), per-module / per-sub-project context, codified indexes, subagents, slash commands, guardrails, Copilot instructions, Continue rules, Cline / Windsurf rule files — ships ready to use.

Optional follow-ups (not blockers):

• Review TODO markers in .aem/context/conventions.md / avoid.md / glossary.md / test-patterns.md. These appear when a derived rule had fewer than 3 evidence samples.
• Customize the role-prompts in .claude/agents/ etc. if the team has additional conventions not derivable from code.

Known gaps and what's deferred to v0.2

Area	v0.1 behavior	v0.2 plan
Guardrail enforcement	Advisory text. Agent that ignores indexes can still create duplicates.	MCP aem-agentkit-check pre-edit hook that fails loudly.
Index self-update	Author roles include a mandatory final step in the prompt. Advisory.	Same enforcement track as guardrails.
Live Javadoc lookup	Static aem-api-namespaces.md covers package roots; agent uses web search for class verification.	MCP tool resolving com.adobe.cq.<class> against Cloud Service Javadoc.
Git submodules	Out of scope. Each submodule needs the skill run from its own root.	A /agents-md-submodules command walking .gitmodules with guidance per submodule.
CI integration	No GitHub Action. /agents-md-check is invoked by humans on demand.	Sample workflow running /agents-md-check on every PR.
Real MCP server commands	Placeholder only.	Detect installed packages via npm ls and pre-wire real commands.
Customer-named module purpose	Heuristics for code-quality, analysis, custom frontend. Other names fall back to generic.	Broader pom-content heuristics; user-defined module hints.
Universal Editor / Edge Delivery specifics	Signals noted in conventions.md. No dedicated subagent.	Dedicated subagents per integration if customer demand surfaces.
Dry-run mode	Procedural skill can be asked "show me what you would do without writing"; atomic writes mean the customer can always revert.	Formal --dry-run flag.

Post-run preview: aem-guides-wknd (standard archetype)

Detected: Java 21, no mvnw, cloud dispatcher, only .github/ present → universal layer + Copilot layer. Only new files (no existing file modified):

aem-guides-wknd/
├── .aem/
│   └── context/
│       ├── README.md
│       ├── components.json          # ~32 components: accordion, breadcrumb,
│       │                            # button, byline, carousel, container,
│       │                            # contentfragment, … through xfpage
│       ├── osgi-services.json       # 3 Sling Models + PermissionCheckServlet
│       ├── conventions.md           # package=com.adobe.aem.guides.wknd.*
│       │                            # JUnit 5 + AemContextExtension + Mockito
│       ├── avoid.md                 # likely empty (clean repo)
│       ├── glossary.md              # WKND terms from cq:title values
│       ├── test-patterns.md
│       └── aem-api-namespaces.md
├── core/AGENTS.md
├── ui.frontend/AGENTS.md            # General Webpack / TypeScript variant
├── ui.apps/AGENTS.md
├── ui.apps.structure/AGENTS.md
├── ui.config/AGENTS.md
├── ui.content/AGENTS.md
├── ui.content.sample/AGENTS.md
├── it.tests/AGENTS.md
├── dispatcher/AGENTS.md             # cloud layout
├── ui.tests/AGENTS.md
├── all/AGENTS.md
└── .github/
    ├── copilot-instructions.md      # only if missing
    └── instructions/
        ├── aem-guardrails.instructions.md            # applyTo: **/*
        ├── aem-component-author.instructions.md      # applyTo: **/ui.apps/**
        ├── aem-sling-model-author.instructions.md    # applyTo: **/src/main/java/**
        ├── aem-htl-author.instructions.md            # applyTo: **/*.html
        ├── aem-dispatcher-editor.instructions.md     # applyTo: dispatcher/**
        ├── aem-osgi-config-author.instructions.md    # applyTo: **/ui.config/**
        ├── aem-integration-test-author.instructions.md # applyTo: **/it.tests/**
        └── aem-ui-test-author.instructions.md        # applyTo: **/ui.tests/**

Post-run preview: nested AEM monorepo

When the root pom's <modules> include full AEM archetypes (each carrying its own core/, ui.apps/, ui.frontend/, etc.), recursive sub-project discovery places per-archetype-leaf AGENTS.md at the correct depth and writes a sub-project-scoped .aem/context/ at each nested root.

Hypothetical monorepo/ with two nested AEM projects brand-site-a/ and brand-site-b/:

monorepo/
├── .aem/
│   └── context/                     # shared across the whole monorepo
│       └── (8 files: README.md + components.json + osgi-services.json +
│                     conventions.md + avoid.md + glossary.md +
│                     test-patterns.md + aem-api-namespaces.md)
│
├── brand-site-a/                    # nested AEM project
│   ├── AGENTS.md                    # sub-project overview
│   ├── .aem/context/                # scoped to this sub-project only (8 files)
│   ├── core/AGENTS.md
│   ├── ui.apps/AGENTS.md
│   ├── ui.frontend/AGENTS.md
│   ├── ui.config/AGENTS.md
│   ├── ui.content/AGENTS.md
│   ├── ui.apps.structure/AGENTS.md
│   └── all/AGENTS.md
│
├── brand-site-b/                    # nested AEM project, same layout
│   └── …
│
├── shared-frontend/AGENTS.md        # leaf — frontend variant template
├── code-quality/AGENTS.md           # leaf — code-quality template (new)
├── analyse/AGENTS.md                # leaf — analysis template (new)
├── dispatcher/AGENTS.md             # leaf — dispatcher template
├── it.tests/AGENTS.md               # leaf
├── ui.tests/AGENTS.md               # leaf
│
├── .claude/
│   ├── agents/                      # 8 author roles + guardrails
│   └── commands/                    # 5 slash commands
├── .mcp.json                        # placeholder if missing
└── .github/
    ├── copilot-instructions.md      # only if missing
    └── instructions/                # 8 scoped instructions

Git submodules at any level are intentionally not descended; each submodule is treated as an independent repo to be bootstrapped from its own root.

Acceptance criteria

1. git status before vs after a run shows zero modifications to any pre-existing file. Only new files appear.
2. No write into .git/, target/, node_modules/, dist/, build/, out/.
3. Every new file carries the aem-agentkit: generated v0.1.0-beta marker (Markdown) or _generatedBy: "aem-agentkit" (JSON).
4. Every evidence pointer in derived Markdown resolves.
5. Per-module AGENTS.md files match the actually-present modules (flat for standard archetype, recursive for nested monorepo).
6. components.json includes the customer's components under ui.apps/.../jcr_root/apps/**.
7. osgi-services.json includes the customer's Sling Models / services / servlets walked across every Java module.
8. /agents-md-check produces a deterministic drift report.
9. Re-running the skill produces no new files and no .agentkit-new files.
10. Running ensure-agents-md after aem-agentkit is a no-op.
11. No artifact contains marketing language; framing uses agentic-workflow terminology only.
12. No off-limits file is read.
13. When every detected tool projection is produced, the canonical role-source body appears verbatim across all projections (byte-identical inside each role across IDEs).
14. With a _disable_agentkit file at workspace root, the skill makes no writes and exits with code 0.
15. With root AGENTS.md already present and no marker, the skill does not touch it.
16. Bumping _skillVersion and re-running produces .agentkit-new files but never overwrites originals.
17. The summary block is produced verbatim with deterministic counts.

Trademarks and licensing

Apache 2.0 (matches the aem-cloud-service plugin). References to third-party IDE and agent names (Claude Code, Cursor, GitHub Copilot, Codex, Continue.dev, Cline, Windsurf, Augment Code, Aider, Gemini CLI, Zed, RooCode, JetBrains Junie, and others) are nominative and descriptive only. All such names remain the trademarks of their respective owners. This skill is not affiliated with or endorsed by any of them. The skill's README.md contains an explicit trademark notice.

CI status

All 9 checks green: tessl-eval, tessl-lint, tessl-review, validate, conventional-commits, codeowners-coverage, license-field, Adobe CLA Signed?, Kodiak.

[github-actions]

Tessl Skill Lint

✅ edge-delivery-services — clean

✅ stardust — clean

---

✅ All 2 tile(s) clean.

Updated by tessl-lint for commit 66acee0.

[abhishekgarg18]

Superseded by #172 — a fresh PR with a single squashed commit and a substantially expanded description that covers context, design decisions, edge cases, update flow, and before/after snapshots for aem-guides-wknd and a multi-brand monorepo. Same skill code, same v1.0.0-beta state, cleaner commit history. Please continue review on #172.