• Onboarding new developers to a project
• Technical handover to maintenance team
• Code review and architecture documentation
• Creating developer-focused documentation

allGuides

cd

ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"allGuides"[[:space:]]*:[[:space:]]*true')
if [ -z "$ALL_GUIDES" ]; then
  # Navigate to git project root (works from any subdirectory)
  cd "$(git rev-parse --show-toplevel)"
  # Verify it's an Edge Delivery Services project
  ls scripts/aem.js
fi

• You MUST run the

  cd

  command above using the Bash tool
• All subsequent steps operate from project root
• Do NOT use absolute paths to verify — actually navigate
• Guides will be created at

  project-root/project-guides/

scripts/aem.js

"This skill is designed for AEM Edge Delivery Services projects. The current directory does not appear to be an Edge Delivery Services project (

scripts/aem.js

not found).

Please navigate to an Edge Delivery Services project and try again."

• NEVER use "EDS" as an acronym for Edge Delivery Services in any generated documentation or chat responses
• Always use the full name "Edge Delivery Services" or "AEM Edge Delivery Services"
• This applies to all output files (PDF, HTML, markdown) and all communication with the user

project-guides/DEVELOPER-GUIDE.md

1. First, create the directory:

   mkdir -p project-guides

2. Then write to:

   project-guides/DEVELOPER-GUIDE.md

project-guides/

DEVELOPER-GUIDE.md

docs/DEVELOPER-GUIDE.md

/workspace/DEVELOPER-GUIDE.md

project-guides/DEVELOPER-GUIDE.md

project-guides/DEVELOPER-GUIDE.pdf

• ❌ Do NOT read or analyze

  fstab.yaml

  — it does NOT exist in most projects and does NOT show all sites
• ❌ Do NOT create

  .plain.html

  files
• ❌ Do NOT use

  convert_markdown_to_html

  tool — this converts the FULL guide to HTML with raw frontmatter visible, which is NOT what we want
• ❌ Do NOT tell user to "convert markdown to PDF manually"
• ❌ Do NOT save markdown to root directory or any path other than

  project-guides/

• ❌ Do NOT say "PDF will be generated later" or "at session end" — generate it NOW

1. Run

   mkdir -p project-guides

   to ensure directory exists
2. Generate markdown content with YAML frontmatter (title, date)
3. Save to

   project-guides/DEVELOPER-GUIDE.md

   (EXACT PATH - no exceptions)
4. IMMEDIATELY invoke PDF conversion (see Phase 5.1)
5. Clean up all source files (only PDF remains)
6. Final output:

   project-guides/DEVELOPER-GUIDE.pdf

"What is your Config Service organization name? This is the

{org}

part of your Edge Delivery Services URLs (e.g.,

https://main--site--{org}.aem.page

). The org name may differ from your GitHub organization."

• DO NOT use

  AskUserQuestion

  with predefined options — ask as a plain text question
• Organization name is MANDATORY — do not offer a "skip" option
• Wait for user to type the org name before proceeding
• If user doesn't provide a valid org name, ask again

• Analyzing

  fstab.yaml

  — does NOT show all sites in repoless setups
• Reading

  README.md

  — may be outdated or incomplete
• Inferring from codebase structure — misses CDN configs and additional sites
• Using git remote URLs — org name may differ from Config Service org
• Making assumptions based on project folder names

ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')

**📁 REQUIRED ARTIFACT:** `.claude-plugin/sites-config.json`

**API Reference:** https://www.aem.live/docs/admin.html#tag/siteConfig/operation/getConfigSites

---

The response is a JSON object with a `sites` array (each entry has a `name` field). Extract site names and construct per-site URLs:
- **Preview:** `https://main--{site-name}--{org}.aem.page/`
- **Live:** `https://main--{site-name}--{org}.aem.live/`

Multiple sites = **repoless** setup. Single site = **standard** setup.

**Then fetch individual site config for code and content details:**

```bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
curl -s -H "x-auth-token: ${AUTH_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

{
  "code": {
    "owner": "github-owner",
    "repo": "repo-name",
    "source": { "type": "github", "url": "https://github.com/owner/repo" }
  },
  "content": {
    "source": {
      "url": "https://content.da.live/org-name/site-name/",
      "type": "markup"
    }
  }
}

• code.owner

  /

  code.repo

  — GitHub repository

• content.source.url

  — Content mountpath (e.g.,

  https://content.da.live/org/site/

  )

• content.source.type

  — Content source type (markup, onedrive, google)

fstab.yaml

--pages-url

aem up

• Include: Items with 2+ commits AND at least one commit after "initial commit"
• Exclude: Items with only 1 commit that is "Initial commit" or similar boilerplate setup
• Exclude: Items with only

  aem-aemy[bot]

  commits (auto-generated)
• Items that only have an "initial commit" were never customized — do NOT document them.

• Vanilla JavaScript (ES6+)
• CSS3 with Custom Properties
• No build step - files served directly
• Content from Document Authoring (DA)

styles/styles.css

scripts/scripts.js

fonts.css

lazy-styles.css

scripts/delayed.js

• Never add third-party scripts to

  scripts.js

  — they block LCP. Always use

  delayed.js

  .
• Never load fonts eagerly —

  fonts.css

  is loaded lazily to avoid render-blocking.
• Blocks in the first section load eagerly; all others load lazily. This is automatic based on DOM position.
• The header and footer are loaded in the lazy phase via

  loadHeader()

  /

  loadFooter()

  from

  aem.js

  .

• Node.js [version from .nvmrc]
• AEM CLI:

  npm install -g @adobe/aem-cli

• URL: http://localhost:3000
• Auto-reload on file changes
• Uses preview content by default

Local Server — Repoless/Multi-Site

For repoless setups with multiple sites sharing one repository, you must specify the site's preview URL when starting the local server:

bash

aem up --pages-url=https://main--{site}--{org}.aem.page

Replace

{site}

and

{org}

with the actual site and organization names from the Config Service.

Without

--pages-url

, the AEM CLI cannot resolve content for the correct site and local preview will fail or show wrong content.

1. Create

   blocks/{name}/{name}.js

2. Create

   blocks/{name}/{name}.css

3. Implement

   export default function decorate(block)

4. Test locally at http://localhost:3000
5. Push to feature branch

1. Edit

   styles/styles.css

2. Use CSS custom properties
3. Test across multiple pages
4. Watch for CLS impact

1. Add to

   scripts/delayed.js

2. Never add to

   scripts.js

   (blocks performance)
3. Test with Network tab to verify delayed loading

1. Check browser console for errors
2. Inspect DOM: expected structure vs actual
3. Check if variant classes are applied
4. Verify CSS specificity

• Features:

  feature/description

• Fixes:

  fix/description

• Keep names short (URL length limits)

1. Include preview URL in PR description
2. Pass linting
3. Test on feature branch preview
4. No console errors

1. Check block folder name matches class name
2. Verify JS exports

   default function decorate

3. Check browser Network tab for 404s

1. Check CSS specificity
2. Verify file is loading (Network tab)
3. Check for CSS syntax errors

1. Clear browser cache
2. Check preview was triggered in DA
3. Wait for CDN cache (1-2 min)

1. Save markdown to:

   project-guides/DEVELOPER-GUIDE.md

   • File MUST start with YAML frontmatter:
     yaml

     ---
     title: "[Project Name] - Developer Guide"
     date: "[Full Date - e.g., February 17, 2026]"
     ---

   • Date format: Always use full date with day, month, and year (e.g., "February 17, 2026"), NOT just month and year
2. IMMEDIATELY after saving the markdown, invoke the PDF conversion skill:

   Skill({ skill: "project-management:whitepaper", args: "project-guides/DEVELOPER-GUIDE.md project-guides/DEVELOPER-GUIDE.pdf" })

3. Wait for PDF generation to complete (whitepaper skill auto-cleans source files)

• Skip the PDF conversion step
• Tell user "PDF will be generated later" — generate it NOW

• Config Service API was called (

  https://admin.hlx.page/config/{ORG}/sites.json

  )
• Site list came from API response, NOT from fstab.yaml or codebase analysis
• Repoless/standard determination came from Config Service, NOT inferred from code

• Quick Reference with all project URLs
• Architecture overview accurate to project
• Design system fully documented (tokens, fonts, breakpoints)
• Project-specific blocks documented
• Custom scripts.js functions documented
• delayed.js integrations documented
• Templates documented (if applicable)
• Local development setup verified
• Common tasks have clear instructions
• Troubleshooting section covers common issues
• Resources linked

• PDF generated successfully
• All source files cleaned up (only PDF remains)

1. Focus on what's unique - Document project-specific implementations
2. Use code examples - Show actual code from the project
3. Document the "why" - Explain reasoning behind custom implementations
4. Include gotchas - Note any tricky behavior or edge cases
5. Test the setup instructions - Verify they work from scratch
6. Keep it maintainable - Don't over-document things that change often