back
loading skill details...
Generate comprehensive admin documentation for AEM Edge Delivery Services project handover. Creates admin guide covering Config Service setup, permissions,…
Project Handover - Admin Guide
Generate comprehensive documentation for administrators taking over an AEM Edge Delivery Services project. Produces a complete admin guide with Config Service setup, permissions, Admin API operations, and troubleshooting.
When to Use This Skill
Project handover to client administrators
Documenting admin procedures for a project
Creating operations runbook
"Generate admin guide"
"Admin documentation"
"Admin handover"
Step 0: Navigate to Project Root and Verify Edge Delivery Services Project (CONDITIONAL)
Skip this step if allGuides flag is set (orchestrator already validated and navigated).
CRITICAL: If NOT skipped, you MUST execute the cd command. Do NOT use absolute paths — actually change directory.
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
IMPORTANT:
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/
If NOT skipped AND scripts/aem.js does NOT exist, respond:
"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."
STOP if check fails. Otherwise proceed — you are now at project root.
Execution Checklist
- [ ] Phase 1: Gather Project Context
- [ ] Phase 2: Generate Admin Guide Content
- [ ] Phase 3: Customize for Project
- [ ] Phase 4: Generate Professional PDF
Communication Guidelines
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
⚠️ CRITICAL PATH REQUIREMENT
YOU MUST SAVE THE FILE TO THIS EXACT PATH:
project-guides/ADMIN-GUIDE.md
BEFORE WRITING ANY FILE:
First, create the directory: mkdir -p project-guides
Then write to: project-guides/ADMIN-GUIDE.md
WHY THIS MATTERS: Files must be in project-guides/ for proper organization and PDF conversion.
❌ WRONG: ADMIN-GUIDE.md (root)
❌ WRONG: docs/ADMIN-GUIDE.md
❌ WRONG: /workspace/ADMIN-GUIDE.md
✅ CORRECT: project-guides/ADMIN-GUIDE.md
Output Format
MANDATORY OUTPUT: project-guides/ADMIN-GUIDE.pdf
STRICTLY FORBIDDEN:
❌ 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
The HTML output must be a SHORT summary page (created with Write tool) containing:
Title and brief description
"What's Inside" bullet list
PDF download link
NOT the full guide content converted to HTML.
REQUIRED WORKFLOW:
Run mkdir -p project-guides to ensure directory exists
Generate markdown content with YAML frontmatter (title, date)
Save to project-guides/ADMIN-GUIDE.md (EXACT PATH - no exceptions)
IMMEDIATELY invoke PDF conversion (see Phase 4.1)
Clean up all source files (only PDF remains)
Final output: project-guides/ADMIN-GUIDE.pdf
Phase 0: Get Organization Name (Required First)
Whenever this skill runs — whether the user triggered it directly (e.g. "generate admin guide") or via the handover flow — you must have the Config Service organization name before doing anything else. Do not skip this phase.
0.1 Check for Saved Organization
# Check if org name is already saved
cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1
0.2 Prompt for Organization Name (If Not Saved)
If no org name is saved, you MUST pause and ask the user directly:
"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."
IMPORTANT RULES:
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
0.3 Save Organization Name
Once you have the org name (either from saved config or user input), save it for future use:
# Create config directory if needed
mkdir -p .claude-plugin
# Ensure .claude-plugin is in .gitignore (contains auth tokens)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
# Save org name to config file (create or update)
if [ -f .claude-plugin/project-config.json ]; then
cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]*:[[:space:]]*"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json
else
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
fi
Replace {ORG_NAME} with the actual organization name provided by the user.
Phase 0.5: Authenticate with Config Service (Browser Login)
After getting the organization name, authenticate using Playwright browser automation.
0.5.1 Check for Existing Auth Token
# Check if auth token is already saved
AUTH_TOKEN=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
if [ -n "$AUTH_TOKEN" ]; then
echo "Auth token found"
else
echo "No auth token - need to authenticate"
fi
0.5.2 Open Browser for Login (If No Token)
If no auth token exists, use Playwright CLI:
Install Playwright (if needed):
npx playwright --version 2>/dev/null || npm install -g playwright
npx playwright install chromium 2>/dev/null || true
Get the first site name (unauthenticated endpoint):
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
SITE=$(curl -s "https://admin.hlx.page/config/${ORG}/sites.json" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"name"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
Display clear instructions and open browser:
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║ ║"
echo "║ BROWSER WINDOW OPENING FOR ADOBE ID LOGIN ║"
echo "║ ║"
echo "║ 1. Sign in with your Adobe ID credentials ║"
echo "║ 2. After successful login, CLOSE THE BROWSER WINDOW ║"
echo "║ ║"
echo "║ >>> CLOSE THE BROWSER TO CONTINUE <<< ║"
echo "║ ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""
mkdir -p .claude-plugin
npx playwright open --save-storage=.claude-plugin/auth-storage.json "https://admin.hlx.page/login/${ORG}/${SITE}/main"
0.5.3 Extract and Save Auth Token
After browser is closed, extract token from storage file:
echo "Browser closed. Extracting auth token..."
AUTH_TOKEN=$(node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('.claude-plugin/auth-storage.json', 'utf8'));
const cookie = data.cookies.find(c => c.name === 'auth_token');
console.log(cookie ? cookie.value : '');
")
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
echo "{\"org\": \"${ORG}\", \"authToken\": \"${AUTH_TOKEN}\"}" > .claude-plugin/project-config.json
rm -f .claude-plugin/auth-storage.json
echo "Auth token saved."
0.5.4 Verify Authentication
Test the token works:
AUTH_TOKEN=$(cat .claude-plugin/project-config.json | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
# Test with authenticated endpoint
curl -s -w "%{http_code}" -o /dev/null -H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites.json"
If returns 200, authentication is successful. If 401, re-authenticate.
Phase 1: Gather Project Context
1.1 Fetch Sites and Code Repo via Config Service API
⚠️ MANDATORY DATA SOURCE — NO ALTERNATIVES ALLOWED
You MUST call the Config Service API. This is the ONLY acceptable source for site information.
❌ PROHIBITED APPROACHES (will produce incorrect results):
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
✅ REQUIRED: Execute and save response:
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
# Save response to file - Step 1.2 depends on this file
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json
📁 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:
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"
Example response:
{
"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"
}
}
}
Extract from response:
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)
⚠️ Do NOT use fstab.yaml — use Config Service API instead.
1.2 Build Context
Read from artifact created in 1.1:
cat .claude-plugin/sites-config.json
Parse the JSON to extract site names, then fetch each site's config for code repo:
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Use these API responses to build context: site names, code repo (owner/repo), preview/live URLs. If site config includes a content source (e.g. content.da.live path), record it for the Sites table.
Admin Context:
├── Organization: {org from saved config}
├── Site(s): {site1}, {site2}, ... (from Config Service API response)
├── Setup Type: {repoless | standard} (from Config Service API)
├── Code Repo: {code.owner}/{code.repo} (from Config Service — GitHub or Cloud Manager)
├── Preview: https://main--{site}--{org}.aem.page/
├── Live: https://main--{site}--{org}.aem.live/
├── Login URL: https://admin.hlx.page/login/{org}/{site}
└── Config Service: https://admin.hlx.page/config/{org}/
Phase 2: Generate Admin Guide
Output File: project-guides/ADMIN-GUIDE.md
Generate the admin handover document with the following structure:
# [Project Name] - Admin Guide
Complete administration guide for managing this Edge Delivery Services project.
## Quick Reference
### URLs
| Purpose | URL |
|---------|-----|
| **Login** | https://admin.hlx.page/login/{org}/{site} |
| **Config Service** | https://admin.hlx.page/config/{org}/ |
| **Preview** | https://main--{site}--{org}.aem.page/ |
| **Live** | https://main--{site}--{org}.aem.live/ |
### Sites (if multi-site/repoless)
| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config if present] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |
| {site2} | [from site config if present] | https://main--{site2}--{org}.aem.page/ | https://main--{site2}--{org}.aem.live/ |
## Authentication
### Login
1. Open: https://admin.hlx.page/login/{org}/{site}
2. Sign in with your Adobe ID
3. Copy auth token for API operations
### Logout
```bash
curl -X POST \
-H "x-auth-token: $AUTH_TOKEN" \
"https://admin.hlx.page/logout/{org}/{site}/main"
User Management
View Current Access
curl -H "x-auth-token: $AUTH_TOKEN" \
"https://admin.hlx.page/config/{org}/sites/{site}/access.json"
Add User
Role
Command
Admin
POST /config/{org}/sites/{site}/access/admin.json with {"users": ["email"]}
Author
POST /config/{org}/sites/{site}/access/author.json with {"users": ["email"]}
Remove User
curl -X DELETE \
-H "x-auth-token: $AUTH_TOKEN" \
"https://admin.hlx.page/config/{org}/sites/{site}/access/admin/{email}.json"
Content Operations
Preview
Operation
Endpoint
Single page
POST /preview/{org}/{site}/main/{path}
Bulk preview
POST /preview/{org}/{site}/main/*
Publish
Operation
Endpoint
Single page
POST /live/{org}/{site}/main/{path}
Bulk publish
POST /live/{org}/{site}/main/*
Unpublish
DELETE /live/{org}/{site}/main/{path}
Cache
Operation
Endpoint
Purge path
POST /cache/{org}/{site}/main/{path}
Purge all
POST /cache/{org}/{site}/main/*
Code Operations
Sync Code
curl -X POST \
-H "x-auth-token: $AUTH_TOKEN" \
"https://admin.hlx.page/code/{owner}/{repo}/main"
Common Tasks
Task
Steps
Add new admin
POST to /config/{org}/sites/{site}/access/admin.json
Republish site
POST to /preview/{org}/{site}/main/* then /live/{org}/{site}/main/*
Clear all cache
POST to /cache/{org}/{site}/main/*
Deploy code changes
POST to /code/{owner}/{repo}/main
Troubleshooting
Issue
Solution
401 Unauthorized
Token expired - login again
403 Forbidden
Insufficient permissions - check role
404 Not Found
Check org/site/path spelling
429 Rate Limited
Wait and retry
Cache not clearing
Try with forceUpdate: true
Code not syncing
Manual sync: POST to /code/{owner}/{repo}/main
Resources
Resource
URL
Admin API Docs
https://www.aem.live/docs/admin.html
Config Service
https://www.aem.live/docs/config-service-setup
## Phase 3: Customize for Project
### 3.1 Fill in Project-Specific Values
Replace all placeholders:
- `{org}` → actual organization from Config Service API
- `{site}` → actual site name(s)
- `{owner}` → code owner from Config Service (GitHub org or Cloud Manager program)
- `{repo}` → code repo from Config Service
### 3.2 Add Multi-Site Details (if repoless)
If project has multiple sites, add a section listing all sites with their:
- Site name
- Preview URL
- Live URL
- Content source
### 3.3 Document Project-Specific Configurations
Check for and document:
- Custom headers (`/config/{org}/sites/{site}/headers.json`)
- CDN configuration
- Any project-specific admin procedures
---
## Phase 4: Convert to Professional PDF
### 4.1 Generate PDF (MANDATORY)
**THIS STEP IS NOT OPTIONAL. YOU MUST GENERATE THE PDF NOW.**
1. Save markdown to: `project-guides/ADMIN-GUIDE.md`
- File MUST start with YAML frontmatter:
```yaml
---
title: "[Project Name] - Admin 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/ADMIN-GUIDE.md project-guides/ADMIN-GUIDE.pdf" })
3. Wait for PDF generation to complete (whitepaper skill auto-cleans source files)
**DO NOT:**
- Skip the PDF conversion step
- Tell user "PDF will be generated later" — generate it NOW
### 4.2 Deliver to User
After PDF is generated, inform the user:
"✓ Admin guide complete: project-guides/ADMIN-GUIDE.pdf"
---
## Output
**FINAL OUTPUT:** `project-guides/ADMIN-GUIDE.pdf`
All source files (.md, .html, .plain.html) are deleted after PDF generation. Only the PDF remains.
**Location:** `project-guides/` folder
---
## Success Criteria
**Data Source Validation (CRITICAL):**
- [ ] 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
- [ ] Code repo info came from site config API, NOT from git remote
**Content Validation:**
- [ ] All org/site values filled from Config Service API
- [ ] Login URL correct
- [ ] All API endpoints have correct org/site
- [ ] Multi-site documented (if applicable)
- [ ] Common tasks listed with correct paths
**Output Validation:**
- [ ] PDF generated successfully
- [ ] All source files cleaned up (only PDF remains)
---
## Tips
1. **Always use Config Service API** - org/site/code repo may differ from what's in the local git remote
2. **Test login URL** - Verify the login URL works before documenting
3. **List all sites** - For repoless setups, document every site
4. **Include examples** - Show actual paths from the projectdon't have the plugin yet? install it then click "run inline in claude" again.