From dx-aem
Generate AEM demo documentation — find or create docs page with configured component, capture dialog and website screenshots on QA, write authoring guide. Extends /aem-editorial-guide for automated pipeline use. Invoked by /dx-agent-all Phase 7 and /dx-req-dod.
npx claudepluginhub easingthemes/dx-aem-flow --plugin dx-aemThis skill is limited to using the following tools:
**Platform note:** This skill uses `context: fork` + `agent: aem-editorial-guide-capture` for isolated execution. If subagent dispatch is unavailable (e.g., VS Code Chat), you may run inline but AEM MCP tools (`AEM/*`, `chrome-devtools-mcp/*`) must be available. If they are not, inform the user: "AEM doc generation requires AEM and Chrome DevTools MCP servers. Please use Claude Code or Copilot ...
Generates authoring guide for AEM Edge Delivery Services projects by analyzing structure for blocks, templates, configurations, and publishing workflows. For content author onboarding and handovers.
Orchestrates content-first development workflow for AEM Edge Delivery Services. Ensures test content exists before implementing JS/CSS/block changes, bug fixes, or core functionality.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Platform note: This skill uses context: fork + agent: aem-editorial-guide-capture for isolated execution. If subagent dispatch is unavailable (e.g., VS Code Chat), you may run inline but AEM MCP tools (AEM/*, chrome-devtools-mcp/*) must be available. If they are not, inform the user: "AEM doc generation requires AEM and Chrome DevTools MCP servers. Please use Claude Code or Copilot CLI."
You generate AEM component demo documentation from completed spec files. You find or create a docs page, configure the component, capture dialog and website screenshots, and write an authoring guide with Authoring and Website sections.
SPEC_DIR=$(bash .ai/lib/dx-common.sh find-spec-dir <work-item-id-if-provided>)
If the script exits with error, ask the user for the work item ID.
Read .ai/config.yaml for:
aem.author-url (defaults to http://localhost:4502)aem.author-url-qa — QA author URLaem.publish-url (defaults to http://localhost:4503)aem.publish-url-qa — QA publisher URLaem.resource-type-pattern — component resource type patternaem.demo-parent-path — parent path for all AI-created demo pages (e.g., /content/brand-a/ca/en/ca/en/demo)PIPELINE_MODE=true (check via Bash: echo "$PIPELINE_MODE") or caller passes --qa: use aem.author-url-qa and aem.publish-url-qaaem.author-url and aem.publish-urlSet $AUTHOR_URL and $PUBLISH_URL for the rest of the flow.
Read these files from $SPEC_DIR (all optional):
explain.md — what was implemented (to identify the component)implement.md — plan steps (component names, file paths)aem-after.md — post-deployment component state (dialog fields, properties, pages)aem-before.md — pre-development baseline (fallback if aem-after.md missing)Determine the target component name from spec files, in order of priority:
aem-after.md — component name in headerimplement.md — step titles mentioning a component nameexplain.md — requirements referencing a specific componentIf no component can be identified, print "Cannot identify target component — provide a component name" and STOP.
demo/authoring-guide.md exists in the spec directorydemo already up to date — skipping and STOPTest AEM connectivity:
curl -sf -o /dev/null -w "%{http_code}" "$AUTHOR_URL/libs/granite/core/content/login.html" || echo "unreachable"
For QA URLs, also try with Basic Auth. Read credentials from .claude/rules/qa-basic-auth.md (or from .ai/config.yaml aem.qa-basic-auth):
curl -sf -o /dev/null -w "%{http_code}" -u "$QA_USER:$QA_PASS" "$AUTHOR_URL/libs/granite/core/content/login.html" || echo "unreachable"
If unreachable:
AEM instance at <url> is not available — generating text-only guide (no screenshots).Use the aem-inspector agent to query AEM for pages using this component's resourceType:
Find all pages using component <component-name> (resourceType: <resource-type>). Return the first 5 page paths with full author URLs.
Save the list for the authoring guide. These are existing production/content pages — useful reference for editors.
Check $SPEC_DIR/demo/page-structure.md cache first. If cached and still valid, use it.
If not cached, discover from the first existing page (from step 7) or from aem-after.md:
Use the aem-inspector agent:
Discover page structure from <page-path>:
- Language root (handle doubled country/lang/country/lang pattern)
- Template used by the page
- Container chain from jcr:content/root to the component
Save findings to $SPEC_DIR/demo/page-structure.md
Read shared/demo-page-setup.md for the Page Selection Rule.
Key rule: New pages are ONLY for new components. For updates to existing components (enhancements, a11y fixes), find the best representative existing page with the component and reuse it. Only create a new page if the component is truly new and not on any existing page.
Priority order for page selection:
aem-after.md for a "Test Page" or "Demo Page" path. If found, reuse it.<demo-parent-path>/<feature-title-slug>.Read aem.demo-parent-path from .ai/config.yaml. If not set, fall back to <language-root>/demo.
Use the aem-inspector agent:
Create a demo page at <demo-parent-path>/<slug> using template <template>.
Recreate the container chain: <chain from page-structure.md>.
Add component <component-name> and configure it with real data from an existing authored instance (search via AEM MCP). Use aem-after.md or implement.md values only as fallback for fields with no real data.
If the page already exists, reuse it (idempotent). Same JCR path works on both local and QA — just use the appropriate author URL.
Use the aem-editorial-guide-capture agent:
$AUTHOR_URL/editor.html<docs-page-path>.html$SPEC_DIR/demo/dialog-<component>.pngSkip if AEM was unavailable (step 6) or if $PUBLISH_URL is not configured.
Use the aem-inspector agent:
Publish the page at <docs-page-path> using mcp__plugin_dx-aem_AEM__activatePage.
Poll the publisher URL for a 200 response, up to 60s timeout:
for i in $(seq 1 12); do
STATUS=$(curl -sf -o /dev/null -w "%{http_code}" -u "$QA_USER:$QA_PASS" "$PUBLISH_URL<docs-page-path>.html" 2>/dev/null)
[ "$STATUS" = "200" ] && break
sleep 5
done
If still not available after 60s, skip website screenshot and note in guide.
Use the aem-editorial-guide-capture agent in publisher view mode:
$PUBLISH_URL<docs-page-path>.html$SPEC_DIR/demo/rendered-<component>.pngWrite $SPEC_DIR/demo/authoring-guide.md:
# <Component Name> — Authoring Guide
## Existing Pages
| # | Page | Author URL |
|---|------|------------|
| 1 | <page-path> | <full author URL> |
| 2 | ... | ... |
...up to 5
## Authoring
### What Changed
<1-3 sentences explaining what's new in plain English, no code references.
Pull from explain.md and implement.md.>
### How to Use
<Per-field descriptions from aem-after.md dialog fields.
For each field: what it does, when to use it, any conditional visibility.>
### Tips
- <Any conditional visibility: "Enable X to reveal additional fields">
- <Any gotchas: "Leave blank to use the default value">
- <Any recommendations: "Use short titles (under 50 characters) for best display">
### Dialog Screenshot

**Author URL:** <author editor URL to docs page>
## Website
### Rendered Component

**Publisher URL:** <publisher URL to docs page>
Writing principles (same as /aem-editorial-guide):
If AEM was unavailable (step 6), omit the Screenshots and Website sections and add a note: "Screenshots unavailable — AEM instance was not reachable during documentation generation."
If publisher screenshot failed (step 11), omit the Website section and add a note: "Website screenshot unavailable — publisher did not respond within timeout."
## aem-doc-gen complete
**Component:** <name>
**Docs Page:** <page path>
**Environment:** <local / QA>
**Output:**
- `demo/authoring-guide.md`
- `demo/dialog-<component>.png` (if captured)
- `demo/rendered-<component>.png` (if captured)
- `demo/page-structure.md` (if discovered)
**Existing Pages:** <count> found
**Author URL:** <url>
**Publisher URL:** <url>
**AEM:** <connected / unavailable>
/aem-doc-gen hero 2416553 — Finds the spec directory for story #2416553, discovers demo/authoring-guide.md from a prior /aem-editorial-guide run. Connects to AEM, locates or creates a docs page with the hero component configured, captures dialog and rendered screenshots on QA, and writes the enhanced authoring guide with field descriptions, screenshots, and publisher URLs.
/aem-doc-gen card (no prior demo) — No existing demo/authoring-guide.md found. Runs the full flow: finds the card component on AEM, captures dialog structure, takes screenshots, and generates the authoring guide from scratch. Saves to the most recent spec directory.
/aem-doc-gen productlisting 2416553 (AEM unavailable) — AEM author is not reachable. Degrades gracefully to text-only mode: reads dialog XML from source, generates an authoring guide without screenshots. Notes "AEM unavailable — screenshots not captured" in the output.
"No spec directory found"
Cause: No spec directory exists for the given work item ID.
Fix: Run /dx-req <id> first to create the spec directory, or provide the correct work item ID.
Screenshots captured but images are dark or empty Cause: The component requires specific content/configuration to render, or the page hasn't fully loaded. Fix: Pre-configure the component on the demo page with sample content, then re-run. The skill will capture whatever is currently rendered.
"AEM unavailable — screenshots not captured"
Cause: AEM author instance is not running or not reachable.
Fix: Start AEM or check aem.author-url in .ai/config.yaml. The text-only guide is still useful — re-run with AEM available to add screenshots later.
localhost:4502 or component pathsPIPELINE_MODE=true, always use QA URLsdemo/page-structure.md to avoid re-discovery on subsequent runs