
aem-project-management
Project lifecycle management for AEM Edge Delivery Services
- version
- 1.0.1
- GitHub stars
- 332
Install
/plugin install aem-project-management@adobe-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 7
AEM Edge Delivery Services Authentication
Authenticate to obtain a token for all Edge Delivery Services admin operations. Auto-detects identity provider from org+site — no content source question needed. Opens the user's default browser for login and receives the token via a local callback server.
Token Usage
The authToken works for admin APIs:
| API | Header | Usage |
|---|---|---|
admin.hlx.page | x-auth-token: ${AUTH_TOKEN} | Preview, publish, status, code sync, jobs, logs, config |
| Config Service | x-auth-token: ${AUTH_TOKEN} | Sites, config, secrets, API keys, profiles |
Note:
admin.da.liveuses a separate Adobe IMS token withAuthorization: Bearerheader. See the DA-specific login flow inops/resources/da.md.
When to Use This Skill
- API returns 401 Unauthorized
- User says "login", "authenticate", "auth"
- Before any admin operation when token is missing/expired
- Before generating guides that need API access
Prerequisites
- Node.js installed
Authentication Flow
Step 1: Check Existing Token
Tokens are cached at the user level (~/.aem/ims-token.json), shared across all projects.
mkdir -p "${HOME}/.aem"
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.authToken);
}
} catch (e) {}
")
if [ -n "$AUTH_TOKEN" ]; then
echo "Token valid"
exit 0
fi
echo "Token missing or expired. Starting login..."
Step 2: Resolve Org and Site
The auto-login endpoint /login/{org}/{site}/main redirects to the correct identity provider automatically — no need to know the content source.
Resolve org and site from available sources (project-config, ops-config, git remote):
# Try project-config first (handover context)
ORG=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { process.stdout.write(JSON.parse(d).org || ''); } catch(e) {}
")
# Fallback to ops-config (ops context)
if [ -z "$ORG" ]; then
ORG=$(node -e "
const fs = require('fs');
try {
const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
process.stdout.write(c.org || '');
} catch(e) {}
")
fi
# Site: try git remote first, then ops-config
SITE=$(basename -s .git $(git remote get-url origin 2>/dev/null) 2>/dev/null)
if [ -z "$SITE" ]; then
SITE=$(node -e "
const fs = require('fs');
try {
const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
process.stdout.write(c.site || '');
} catch(e) {}
")
fi
echo "org=${ORG:-NOT SET} site=${SITE:-NOT SET}"
If ORG is empty, ask the user:
"I need your organization name to authenticate. You can provide either:
- The org name (the
{org}inhttps://main--site--{org}.aem.page)- A preview/live URL like
https://main--mysite--myorg.aem.page/"
If user provides a URL, parse org and site from it:
URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
HOST_PART=$(echo "$URL" | cut -d'/' -f3 | cut -d'.' -f1)
ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
SITE=$(echo "$HOST_PART" | awk -F'--' '{print $(NF-1)}')
echo "Parsed from URL: org=$ORG site=$SITE"
fi
If SITE is still empty (not in a git repo and no URL provided), ask the user:
"I also need a site name to auto-detect your login provider. What is your site name? (the
{site}part ofhttps://main--{site}--{org}.aem.page)"
Do NOT proceed until both org and site are available.
Step 3: Capture Token via Loopback Redirect
Opens the user's default browser for login. A temporary local HTTP server receives the token callback after login completes. The user must click "Send" on the confirmation page to deliver the token. Works with all identity providers (Adobe IMS, Google, Microsoft).
User-facing message (display BEFORE running the script below):
Browser opened for login to
{org}/{site}. Click "Send" after authenticating — you can close the tab once done.
Use bold/highlighted formatting so the instruction stands out clearly.
mkdir -p "${HOME}/.aem"
node -e "
const http = require('http');
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const TOKEN_PATH = path.join(process.env.HOME, '.aem', 'ims-token.json');
const ORG = '${ORG}';
const SITE = '${SITE}';
const STATE = crypto.randomUUID();
const server = http.createServer((req, res) => {
res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
if (req.method === 'OPTIONS') {
res.writeHead(204);
res.end();
return;
}
if (req.method === 'POST') {
let body = '';
req.on('data', (chunk) => { body += chunk; });
req.on('end', () => {
try {
const parsed = JSON.parse(body);
if (parsed.state !== STATE) {
console.error('State mismatch — ignoring callback');
res.writeHead(403);
res.end('State mismatch');
return;
}
const authToken = parsed.authToken;
if (authToken) {
const expiresAt = Math.floor(Date.now() / 1000) + 86400;
fs.writeFileSync(TOKEN_PATH, JSON.stringify({
authToken,
authTokenExpiry: expiresAt,
}, null, 2));
try { fs.chmodSync(TOKEN_PATH, 0o600); } catch (e) {}
console.log('Authentication successful');
console.log('Token cached at: ' + TOKEN_PATH);
console.log('Expires: ' + new Date(expiresAt * 1000).toISOString());
} else {
console.error('No authToken in callback. The helix-admin authToken support may not yet be deployed.');
console.error('Keys received: ' + Object.keys(parsed).join(', '));
}
res.writeHead(200, { 'content-type': 'text/plain' });
res.end('OK');
} catch (e) {
console.error('Failed to parse callback: ' + e.message);
res.writeHead(400);
res.end('Bad request');
}
server.close(() => process.exit(0));
});
} else if (req.method === 'GET') {
res.writeHead(200, { 'content-type': 'text/html' });
res.end('<html><body><p>Login complete. You can close this tab.</p><script>window.close()</script></body></html>');
}
});
server.listen(0, () => {
const port = server.address().port;
const redirectUri = 'http://localhost:' + port + '/.aem/cli/login/ack';
const loginUrl = 'https://admin.hlx.page/login/' + ORG + '/' + SITE + '/main?client_id=aem-cli&redirect_uri=' + encodeURIComponent(redirectUri) + '&state=' + STATE + '&selectAccount=true';
console.log('Opening browser for login...');
console.log('URL: ' + loginUrl);
console.log('');
console.log('After logging in, click the Send button to complete authentication.');
try { execSync('open \"' + loginUrl + '\"'); } catch (e) {
try { execSync('xdg-open \"' + loginUrl + '\"'); } catch (e2) {
console.log('Could not open browser. Please open this URL manually:');
console.log(loginUrl);
}
}
});
setTimeout(() => {
console.error('Login timed out after 5 minutes. No callback received.');
process.exit(1);
}, 300000);
"
Token Storage
User-level token cache — ~/.aem/ims-token.json:
{
"authToken": "eyJ...",
"authTokenExpiry": 1780489855
}
| Field | Description |
|---|---|
authToken | Admin JWT from login callback |
authTokenExpiry | Unix timestamp when token expires (~24 hours) |
Shared across every project on this machine. File is written with 0600 permissions.
Using the Token
# Read token from user-level cache
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
# admin.hlx.page and Config Service use the same header
curl -H "x-auth-token: ${AUTH_TOKEN}" "https://admin.hlx.page/status/{org}/{site}/main/"
curl -H "x-auth-token: ${AUTH_TOKEN}" "https://admin.hlx.page/config/{org}/sites.json"
Troubleshooting
| Issue | Solution |
|---|---|
| Browser doesn't open | Manually open the URL printed in the terminal |
| "Send" button not working | Check browser console for errors; ensure no ad-blocker is blocking localhost requests |
| No authToken in callback | The helix-admin PR adding authToken to CLI login response has not yet been deployed |
| Token not received | Ensure you clicked "Send" on the confirmation page before the 5-minute timeout |
| 401 after login | Token expired, re-authenticate |
| 403 on API | User lacks permission for that org/site |
| State mismatch | Another process may have sent a rogue callback; re-run login |
How It Works
- CLI starts a temporary HTTP server on a random localhost port
- Opens the user's default browser to
admin.hlx.page/login/{org}/{site}/mainwithclient_id=aem-cliandredirect_uri=http://localhost:{port}/... - Admin API auto-detects IDP (Google, Microsoft, Adobe) and redirects to login
- User authenticates in their real browser
- After login, admin API shows a confirmation page with a "Send" button
- User clicks "Send" — browser POSTs
{ state, authToken }to localhost - CLI validates state nonce, saves
authTokento~/.aem/ims-token.json, exits
Integration
Called by: ops, handover-admin, handover-author, handover-developer, handover
Skill({ skill: "aem-project-management:auth" })
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.
Step 0: Navigate to Project Root (CONDITIONAL)
Skip if allGuides is set in .claude-plugin/project-config.json (orchestrator already validated).
ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
cd "$(git rev-parse --show-toplevel)"
ls scripts/aem.js
fi
If scripts/aem.js does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.
All subsequent steps operate from project root. Guides are created at project-guides/.
Execution Checklist
- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Fetch project context from Config Service API
- [ ] Phase 2: Generate admin guide content
- [ ] Phase 3: Customize for project
- [ ] Phase 4: Convert to PDF
Phase 0: Get Organization Name and Authenticate
0.1 Check for Saved Organization
cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"
0.2 Prompt for Organization Name (If Not Saved)
If no org name is found, ask the user:
"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."
Ask as a plain text question — not AskUserQuestion with options. Organization name is mandatory; do not offer a skip option.
0.3 Save Organization Name
mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
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.
0.4 Check Auth Token
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.authToken);
}
} catch (e) {}
")
echo "auth=${AUTH_TOKEN:+set}"
If no valid token exists, invoke the auth skill:
Skill({ skill: "aem-project-management:auth" })
0.5 Verify Authentication
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
const d = require('fs').readFileSync(0,'utf8');
console.log(JSON.parse(d).org || '');
")
STATUS=$(curl -s -w "%{http_code}" -o /dev/null \
-H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites.json")
echo "Auth check: HTTP $STATUS"
If not 200, re-run the auth skill before proceeding.
Phase 1: Gather Project Context
1.1 Fetch Sites via Config Service API
The Config Service API is the only reliable source for site information. Do not use fstab.yaml, README, or git remote URLs.
ORG=$(cat .claude-plugin/project-config.json | node -e "
const d = require('fs').readFileSync(0,'utf8');
console.log(JSON.parse(d).org || '');
")
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
"https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json
node -e "
const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
const j = JSON.parse(d);
if (!j.sites || !j.sites.length) {
console.error('No sites returned — verify org name and re-authenticate if needed');
process.exit(1);
}
console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"
If validation fails, verify the org name is correct, re-authenticate, and retry.
1.2 Fetch Per-Site Config
For each site, fetch its config:
curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Extract:
code.owner/code.repo— GitHub repositorycontent.source.url— Content mountpathcontent.source.type— Content source type (markup, onedrive, google)
Multiple sites = repoless setup. Single site = standard setup.
Build context:
Organization: {org}
Site(s): {site1}, {site2}, ...
Setup: {repoless | standard}
Code Repo: {owner}/{repo}
Preview: https://main--{site}--{org}.aem.page/
Live: https://main--{site}--{org}.aem.live/
Login: https://admin.hlx.page/login/{org}/{site}
Config: https://admin.hlx.page/config/{org}/
Phase 2: Generate Admin Guide
Output file: project-guides/ADMIN-GUIDE.md (run mkdir -p project-guides first).
---
title: "[Project Name] - Admin Guide"
date: "[Full Date — e.g., February 17, 2026]"
---
# [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 | Preview | Live |
|------|----------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |
## Authentication
### Login
1. Open: https://admin.hlx.page/login/{org}/{site}
2. Sign in with your credentials
### 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
| Operation | Endpoint |
|---|---|
| Preview page | POST /preview/{org}/{site}/main/{path} |
| Bulk preview | POST /preview/{org}/{site}/main/* |
| Publish page | POST /live/{org}/{site}/main/{path} |
| Bulk publish | POST /live/{org}/{site}/main/* |
| Unpublish | DELETE /live/{org}/{site}/main/{path} |
| Purge cache | 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 /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
Replace all placeholders with values from the Config Service API:
- `{org}` → actual organization name
- `{site}` → actual site name(s)
- `{owner}` / `{repo}` → code owner and repo from site config
If multi-site (repoless), add a section listing all sites with their preview URL, live URL, and content source.
Check for and document project-specific configurations:
- Custom headers: `/config/{org}/sites/{site}/headers.json`
- CDN configuration
- Any project-specific admin procedures
---
## Phase 4: Convert to Professional PDF
Save the completed markdown to `project-guides/ADMIN-GUIDE.md`. The file must start with YAML frontmatter:
```yaml
---
title: "[Project Name] - Admin Guide"
date: "[Full Date — e.g., February 17, 2026]"
---
Immediately invoke PDF conversion:
Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/ADMIN-GUIDE.md project-guides/ADMIN-GUIDE.pdf" })
The whitepaper skill auto-cleans source files. Final output: project-guides/ADMIN-GUIDE.pdf.
Inform the user: "Admin guide complete: project-guides/ADMIN-GUIDE.pdf"
Success Criteria
| Category | Check |
|---|---|
| Data Source | Config Service API called (https://admin.hlx.page/config/{ORG}/sites.json) |
| Data Source | Site list from API response, not fstab.yaml or codebase analysis |
| Data Source | Code repo info from site config API, not git remote |
| Content | All org/site values filled from Config Service API |
| Content | Login URL correct |
| Content | All API endpoints have correct org/site |
| Content | Multi-site documented (if applicable) |
| Content | Common tasks listed with correct paths |
| Output | PDF generated at project-guides/ADMIN-GUIDE.pdf |
| Output | All source files cleaned up (only PDF remains) |
Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.
Project Handover - Authoring
Generate a complete authoring guide for content authors and content managers. Analyzes the project and produces actionable documentation.
Step 0: Navigate to Project Root (CONDITIONAL)
Skip if allGuides is set in .claude-plugin/project-config.json (orchestrator already validated).
ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
cd "$(git rev-parse --show-toplevel)"
ls scripts/aem.js
fi
If scripts/aem.js does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.
All subsequent steps operate from project root. Guides are created at project-guides/.
Execution Checklist
- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Gather project information from Config Service API
- [ ] Phase 2: Analyze content structure
- [ ] Phase 3: Document blocks and templates
- [ ] Phase 4: Document configuration sheets
- [ ] Phase 5: Generate PDF
Phase 0: Get Organization Name and Authenticate
0.1 Check for Saved Organization
cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"
0.2 Prompt for Organization Name (If Not Saved)
If no org name is found, ask the user:
"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."
Ask as a plain text question — not AskUserQuestion with options. Organization name is mandatory.
0.3 Save Organization Name
mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
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.
0.4 Check Auth Token
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.authToken);
}
} catch (e) {}
")
if [ -z "$AUTH_TOKEN" ]; then
echo "AUTH_REQUIRED"
fi
If AUTH_REQUIRED, invoke the auth skill before proceeding:
Skill({ skill: "aem-project-management:auth" })
Phase 1: Gather Project Information
1.1 Fetch Sites via Config Service API
The Config Service API is the only reliable source for site information. Do not use fstab.yaml, README, or git remote URLs.
ORG=$(cat .claude-plugin/project-config.json | node -e "
const d = require('fs').readFileSync(0,'utf8');
console.log(JSON.parse(d).org || '');
")
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
"https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json
node -e "
const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
const j = JSON.parse(d);
if (!j.sites || !j.sites.length) {
console.error('No sites returned — verify org name and re-authenticate if needed');
process.exit(1);
}
console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"
If validation fails, verify the org name is correct, re-authenticate, and retry.
Fetch per-site config for content details:
curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Extract:
code.owner/code.repo— GitHub repositorycontent.source.url— Content mountpath (e.g.,https://content.da.live/org/site/)content.source.type— Content source type (markup, onedrive, google)
Build DA and Block Library URLs from content source:
- DA URL:
https://da.live/#/{org}/{site}/ - Block Library:
https://da.live/#/{org}/{site}/.da/library
Multiple sites = repoless setup. Single site = standard setup.
1.2 Check Multi-Language Support
ls -la /en /fr /de /es /it 2>/dev/null || echo "Check DA for language folders"
Record whether the project is multi-lingual and which languages are supported.
Phase 2: Analyze Content Structure
Read site config from Phase 1:
cat .claude-plugin/sites-config.json
2.1 Analyze Navigation and Footer
ls nav.md footer.md 2>/dev/null || echo "Nav/footer likely in DA"
Document: Navigation and footer location (DA path or local file), menu structure, mobile behavior.
2.2 Identify Page Templates
ls -la templates/ 2>/dev/null && ls templates/
For each template, document: name, purpose, how to apply (metadata setting).
2.3 Section Styles
grep -E "\.section\." styles/styles.css 2>/dev/null | head -15
Document available section styles (e.g., dark, highlight, narrow) for the guide's "Available Section Styles" table.
Phase 3: Document Blocks and Templates
3.1 List and Analyze Blocks
ls blocks/
Run block analysis silently. For each block determine: purpose, variants (from CSS .blockname.variant), and when authors should use it. Document all blocks so authors know what's available.
3.2 Document Templates
For each template found in Phase 2.2, document: name, purpose, required metadata fields, and how to apply (template: name in Metadata block).
3.3 DA and Block Library Paths
Get the content path from the Config Service site config. Block Library URL is https://da.live/#/{content-owner}/{content-path}/.da/library — the path varies by project.
Phase 4: Document Configuration Sheets
4.1 Placeholders
ls placeholders.json 2>/dev/null
Document: location in DA, language sheets, key strings authors might need to update.
4.2 Redirects
ls redirects.json 2>/dev/null
Document: location in DA, format (source → destination columns), when to use.
4.3 Bulk Metadata
ls metadata.json 2>/dev/null
Document: location in DA, URL patterns, which metadata properties are set in bulk.
4.4 Other Configuration Sheets
ls -la *.xlsx *.json 2>/dev/null | grep -v package
Phase 5: Generate Author Guide
5.1 Output File
Save to project-guides/AUTHOR-GUIDE.md (run mkdir -p project-guides first).
---
title: "[Project Name] - Author Guide"
date: "[Full Date — e.g., February 17, 2026]"
---
# [Project Name] - Author Guide
## Quick Reference
| Resource | URL |
|----------|-----|
| Document Authoring | https://da.live/#/{content-owner}/{content-path}/ |
| Preview (per site) | https://main--{site}--{org}.aem.page/ |
| Live (per site) | https://main--{site}--{org}.aem.live/ |
| Block Library | https://da.live/#/{content-owner}/{content-path}/.da/library |
| Bulk Operations | https://da.live/apps/bulk |
(**Content path** comes from the Config Service site config — e.g., `content.da.live/org/site/` → use `org/site` for the path after `#/`. This varies by project.)
### Sites
| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |
## Getting Started
### Access Requirements
- [ ] DA access (request from admin)
- [ ] Preview/publish permissions
### Your First Page
1. Go to DA: [link]
2. Navigate to the correct folder
3. Create new document
4. Use blocks from Library sidebar
5. Add Metadata block at bottom
6. Preview → Publish
## Content Organization
### Site Structure
[Describe the folder structure in DA]
### Languages
[List supported languages if multi-lingual]
## Block Library
The Block Library is the sidebar in Document Authoring where you browse and insert blocks and templates.
| What | Details |
|------|---------|
| **Open in DA** | Use the Library icon in the DA editor sidebar, or go directly to: `https://da.live/#/{content-owner}/{content-path}/.da/library` |
| **How to use** | Click a block or template in the library to insert it at the cursor position |
## Available Blocks
| Block | Purpose | Variants | Usage |
|-------|---------|----------|-------|
| [name] | [what it's for] | [variant1, variant2] | [when to use] |
[Generate table rows for all blocks]
## Page Templates
| Template | Purpose | Required Metadata | How to Apply |
|----------|---------|-------------------|--------------|
| [name] | [what type of pages] | [key fields] | `template: [name]` in Metadata |
[Generate table rows for all templates]
## Configuration Sheets
| Sheet | Location | Purpose | When to Update |
|-------|----------|---------|----------------|
| Placeholders | `/placeholders` | Reusable text strings, translations | Changing labels, button text |
| Redirects | `/redirects` | Forward old URLs to new URLs | After deleting/moving pages |
| Bulk Metadata | `/metadata` | Apply metadata to multiple pages | Setting defaults by folder |
## Publishing Workflow
| Environment | Domain | Purpose |
|-------------|--------|---------|
| Preview | `.aem.page` | Test changes before going live |
| Live | `.aem.live` | Production site |
**Workflow:** Edit in DA → Preview → Publish → Live immediately
**Bulk:** https://da.live/apps/bulk
## Common Tasks
| Task | Steps |
|------|-------|
| **Create a Page** | Navigate to folder → New → Document → Add content → Add Metadata → Preview → Publish |
| **Edit a Page** | Open in DA → Make changes → Preview → Publish |
| **Delete a Page** | Add redirect first → Delete document → Publish redirects |
| **Update Navigation** | Edit `/nav` document → Preview → Publish |
| **Update Footer** | Edit `/footer` document → Preview → Publish |
## Sections and Section Metadata
Sections group content together. Create sections with horizontal rules (`---`).
Add styles with a Section Metadata block at the end of the section:
| Section Metadata | |
|------------------|-|
| style | [style-name] |
**Available Section Styles:**
| Style | Effect |
|-------|--------|
| [List project-specific styles] | |
## Page Metadata
| Property | Required | Purpose | Example |
|----------|----------|---------|---------|
| `title` | Yes | Page title for SEO | "About Us" |
| `description` | Yes | SEO description | "Learn about..." |
| `image` | No | Social sharing image | /images/og.jpg |
| `template` | No | Apply page template | project-article |
| [Add project-specific fields] | | | |
## Images and Media
| Method | How |
|--------|-----|
| Drag & drop | Drag images directly into DA editor |
| AEM Assets | Use Assets sidebar in DA |
Best practices: descriptive filenames, always add alt text, images auto-optimized.
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Page not updating after publish | Wait 1-2 min for cache, hard refresh (Cmd+Shift+R) |
| Block not displaying correctly | Check structure matches expected format, verify variant spelling |
| Images not showing | Verify image uploaded to DA, check path is correct |
| Wrong template styling | Check `template` value in Metadata matches template name exactly |
## Resources
| Resource | URL |
|----------|-----|
| DA Documentation | https://docs.da.live/ |
| Authoring Guide | https://www.aem.live/docs/authoring |
| Placeholders Docs | https://www.aem.live/docs/placeholders |
| Redirects Docs | https://www.aem.live/docs/redirects |
## Support Contacts
[Add project-specific contacts]
5.2 Convert to Professional PDF
Save the completed markdown to project-guides/AUTHOR-GUIDE.md with YAML frontmatter (title, date using full date format e.g., "February 17, 2026"). Then immediately invoke PDF conversion:
Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.pdf" })
The whitepaper skill auto-cleans source files. Final output: project-guides/AUTHOR-GUIDE.pdf.
Inform the user: "Author guide complete: project-guides/AUTHOR-GUIDE.pdf"
Success Criteria
| Category | Check |
|---|---|
| Data Source | Config Service API called (https://admin.hlx.page/config/{ORG}/sites.json) |
| Data Source | Site list from API response, not fstab.yaml or codebase analysis |
| Data Source | DA/Block Library URLs derived from Config Service content source, not assumed from code.owner/repo |
| Content | Quick Reference table with all project URLs |
| Content | All blocks documented in table format |
| Content | All templates documented with required metadata |
| Content | Configuration sheets documented |
| Content | Publishing workflow explained |
| Content | Common tasks documented |
| Content | Section/page metadata options listed |
| Content | Troubleshooting included |
| Output | PDF generated at project-guides/AUTHOR-GUIDE.pdf |
| Output | All source files cleaned up (only PDF remains) |
Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.
Project Handover - Development
Generate a complete technical guide for developers. Analyzes the codebase and produces actionable documentation that enables developers to understand, maintain, and extend the project.
Step 0: Navigate to Project Root (CONDITIONAL)
Skip if allGuides is set in .claude-plugin/project-config.json (orchestrator already validated).
ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
cd "$(git rev-parse --show-toplevel)"
ls scripts/aem.js
fi
If scripts/aem.js does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.
All subsequent steps operate from project root. Guides are created at project-guides/.
Execution Checklist
- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Gather project information
- [ ] Phase 2: Analyze project architecture
- [ ] Phase 3: Document design system
- [ ] Phase 4: Document blocks, models, and templates
- [ ] Phase 5: Generate PDF
Phase 0: Get Organization Name and Authenticate
0.1 Check for Saved Organization
cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"
0.2 Prompt for Organization Name (If Not Saved)
If no org name is found, ask the user:
"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."
Ask as a plain text question — not AskUserQuestion with options. Organization name is mandatory.
0.3 Save Organization Name
mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
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.
0.4 Check Auth Token
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.authToken);
}
} catch (e) {}
")
if [ -z "$AUTH_TOKEN" ]; then
echo "AUTH_REQUIRED"
fi
If AUTH_REQUIRED, invoke the auth skill:
Skill({ skill: "aem-project-management:auth" })
Phase 1: Gather Project Information
1.1 Get Project URLs and Repository
git remote -v | head -1
git branch -a | head -10
Extract: repository owner, repo name, main branch name.
1.2 Check Configuration Method
ls helix-config.yaml 2>/dev/null && echo "Uses legacy helix-config" || echo "Uses Config Service (modern)"
1.3 Fetch Sites via Config Service API
The Config Service API is the only reliable source for site information. Do not use fstab.yaml, README, or git remote URLs.
ORG=$(cat .claude-plugin/project-config.json | node -e "
const d = require('fs').readFileSync(0,'utf8');
console.log(JSON.parse(d).org || '');
")
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
"https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json
node -e "
const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
const j = JSON.parse(d);
if (!j.sites || !j.sites.length) {
console.error('No sites returned — verify org name and re-authenticate if needed');
process.exit(1);
}
console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"
If validation fails, verify the org name is correct, re-authenticate, and retry.
Fetch per-site config:
curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Extract: code.owner, code.repo, content.source.url, content.source.type.
Multiple sites = repoless setup. Single site = standard setup. Record this — it affects the aem up local dev instructions.
1.4 Check Node.js Requirements
cat .nvmrc 2>/dev/null || cat package.json | grep -A2 '"engines"'
Phase 2: Analyze Project Architecture
Read site config:
cat .claude-plugin/sites-config.json
2.1 Map Project Structure
ls -la && ls -la blocks/ && ls -la scripts/ && ls -la styles/
ls -la templates/ 2>/dev/null || echo "No templates folder"
2.2 Identify Boilerplate vs Custom Files
Only document files that were actually customized.
git log --oneline --follow {file_path} | head -5
git log --format="%an - %s" --follow {file_path} | head -5
| Git History | Action |
|---|---|
| Only "Initial commit" | Skip — boilerplate default, never worked on |
Only aem-aemy[bot] commits | Skip — auto-generated |
| Multiple commits by team | Document — customized |
2.3 Analyze scripts/aem.js (Core Library)
grep -E "^export" scripts/aem.js
Document which functions the project imports from aem.js (e.g., sampleRUM, loadHeader, loadFooter, decorateBlock, loadBlock, loadCSS).
2.4 Analyze scripts/scripts.js
grep -E "^import|^export|^function|^async function|buildAutoBlocks|loadTemplate|getLanguage|getSiteRoot|decorateMain|loadEager|loadLazy|loadDelayed" scripts/scripts.js
Document:
| Pattern | What to Document |
|---|---|
import statements | What it imports from aem.js and utils.js |
loadEager / loadLazy | Any custom logic added to E-L-D phases |
buildAutoBlocks | Auto-blocking logic |
loadTemplate / template handling | Template system |
getLanguage / language detection | Multi-language setup |
getSiteRoot / site detection | Multi-site configuration |
| External script loading | Which phase — flag if in eager (performance risk) |
2.5 Analyze the delayed phase
Current boilerplate projects load martech through loadDelayed() → scripts/consent-check.js → scripts/consented.js (after consent). Older projects use scripts/delayed.js. Check whichever the project has:
grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/consented.js scripts/consent-check.js scripts/delayed.js 2>/dev/null
Document analytics integrations, marketing tools, performance monitoring and the consent mechanism. Confirm no render-critical code is in these files.
2.6 Check for Utility Functions
grep -E "^export|^function" scripts/utils.js 2>/dev/null || echo "No utils.js"
ls scripts/*.js
grep -rl "utils.js" blocks/ scripts/ 2>/dev/null
Document shared utility functions and which blocks/scripts import them.
2.7 Check for External Dependencies
grep -A 20 '"dependencies"' package.json 2>/dev/null | head -25
grep -r "cdn\|unpkg\|jsdelivr" scripts/ blocks/ --include="*.js" 2>/dev/null
Phase 3: Document Design System
3.1 Extract CSS Custom Properties
grep -E "^\s*--" styles/styles.css
Organize into categories: Typography, Colors, Spacing, Layout.
3.2 Document Font Setup
grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null
ls fonts/ 2>/dev/null
Document: font files and formats, family names, weights, fallback fonts.
3.3 Document Breakpoints
grep -E "@media.*min-width|@media.*max-width" styles/styles.css | sort -u
Standard breakpoints: Mobile < 600px, Tablet 600-899px, Desktop 900px+, Large 1200px+. Document any deviations.
3.4 Document Section Styles
grep -A 5 "\.section\." styles/styles.css
grep -A 5 "\.section\[" styles/styles.css
Phase 4: Document Blocks, Models, and Templates
Boilerplate Filtering
Run silently — do not show output to user.
- Include: Items with 2+ commits and at least one after "Initial commit"
- Exclude: Items with only "Initial commit" or only
aem-aemy[bot]commits
4.1 Identify and Analyze Customized Blocks
head -30 blocks/{blockname}/{blockname}.js
grep -E "^\." blocks/{blockname}/{blockname}.css | head -30
grep -E "classList\.contains|classList\.add" blocks/{blockname}/{blockname}.js
Document for each customized block:
| Field | What to Record |
|---|---|
| Name | Block folder name |
| Purpose | What it does |
| DOM Input | Expected HTML structure from CMS |
| DOM Output | Transformed structure after decoration |
| Variants | CSS classes that modify behavior |
| Dependencies | External libraries, other blocks, utils |
4.2 Document Universal Editor Models (If Customized)
Apply boilerplate filtering to models/*.json. Exclude standard boilerplate models (_page.json, _section.json, _button.json, _image.json, _text.json, _title.json) if unchanged. Skip section if all models are boilerplate.
4.3 Document Customized Templates
Apply boilerplate filtering to templates/*/. For each customized template, document purpose, how it's applied (template: name in metadata), and what it changes.
Phase 5: Generate Developer Guide
5.1 Output File
Save to project-guides/DEVELOPER-GUIDE.md (run mkdir -p project-guides first).
Read resources/developer-guide-template.md for the full document structure. Fill in all sections using data gathered in Phases 1–4 — replace every [placeholder] with actual project values.
5.2 Convert to Professional PDF
Save the completed markdown to project-guides/DEVELOPER-GUIDE.md with YAML frontmatter (title, date using full date format e.g., "February 17, 2026"). Then immediately invoke PDF conversion:
Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/DEVELOPER-GUIDE.md project-guides/DEVELOPER-GUIDE.pdf" })
The whitepaper skill auto-cleans source files. Final output: project-guides/DEVELOPER-GUIDE.pdf.
Inform the user: "Developer guide complete: project-guides/DEVELOPER-GUIDE.pdf"
Success Criteria
| Category | Check |
|---|---|
| Data Source | Config Service API called (https://admin.hlx.page/config/{ORG}/sites.json) |
| Data Source | Site list from API response, not fstab.yaml or codebase analysis |
| Data Source | Repoless/standard determination from Config Service, not inferred from code |
| Content | Quick Reference with all project URLs |
| Content | Architecture overview accurate to project |
| Content | Design system fully documented (tokens, fonts, breakpoints) |
| Content | Project-specific blocks documented |
| Content | Custom scripts.js functions documented |
| Content | Delayed-phase integrations documented (consented.js or delayed.js) |
| Content | Templates documented (if applicable) |
| Content | Local development setup verified |
| Content | Common tasks have clear instructions |
| Content | Troubleshooting section covers common issues |
| Output | PDF generated at project-guides/DEVELOPER-GUIDE.pdf |
| Output | All source files cleaned up (only PDF remains) |
Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.
Project Handover Documentation
Generate comprehensive handover documentation for Edge Delivery Services projects. Orchestrates the creation of guides for different audiences.
Available Documentation Types
| Guide | Audience | Skill |
|---|---|---|
| Authoring Guide | Content authors and content managers | handover-author |
| Developer Guide | Developers and technical team | handover-developer |
| Admin Guide | Site administrators and operations | handover-admin |
Execution Flow
Step 0: Navigate to Project Root (MANDATORY)
cd "$(git rev-parse --show-toplevel)"
ls scripts/aem.js
If scripts/aem.js does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.
All subsequent steps operate from project root. Guides are created at project-guides/.
Step 0.5: Clean Up Stale Config
rm -f .claude-plugin/project-config.json
Step 1: Ask User for Documentation Type
Use AskUserQuestion with exactly these 4 options:
AskUserQuestion({
"questions": [{
"question": "Which type of handover documentation would you like me to generate?",
"header": "Guide Type",
"options": [
{"label": "All (Recommended)", "description": "Generate all three guides: Authoring, Developer, and Admin"},
{"label": "Authoring Guide", "description": "For content authors and managers - blocks, templates, publishing"},
{"label": "Developer Guide", "description": "For developers - codebase, implementations, design tokens"},
{"label": "Admin Guide", "description": "For site administrators - permissions, API operations, cache"}
],
"multiSelect": false
}]
})
Step 1.5: Get Organization Name
After the user selects guide type(s), ensure the organization name is available before invoking any sub-skills.
1.5.1 Check for Saved Organization
cat .claude-plugin/project-config.json 2>/dev/null | node -e "
const d = require('fs').readFileSync(0,'utf8');
try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"
1.5.2 Resolve Site Name from Git
SITE=$(basename -s .git $(git remote get-url origin 2>/dev/null) 2>/dev/null)
echo "site=${SITE:-NOT SET}"
1.5.3 Prompt for Organization Name (If Not Saved)
If no org name is saved, ask the user:
"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.You can provide either the org name or a preview/live URL."
Ask as a plain text question — not AskUserQuestion with options. Organization name is mandatory.
If the user provides a URL, parse org from it:
URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
HOST_PART=$(echo "$URL" | cut -d'/' -f3 | cut -d'.' -f1)
ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
echo "Parsed from URL: org=$ORG"
fi
1.5.4 Save Organization Name
mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
# Include allGuides flag only when "All (Recommended)" was selected
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
# OR for "All (Recommended)":
echo '{"org": "{ORG_NAME}", "allGuides": true}' > .claude-plugin/project-config.json
Replace {ORG_NAME} with the actual organization name. Include "allGuides": true only when user selected "All (Recommended)" — this signals sub-skills to skip step 0 validation.
Step 1.6: Authenticate
Check for a valid auth token:
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.authToken);
}
} catch (e) {}
")
if [ -n "$AUTH_TOKEN" ]; then
echo "Token valid"
else
echo "Token missing or expired."
fi
If no valid token, invoke the auth skill:
Skill({ skill: "aem-project-management:auth" })
Authenticating here means all sub-skills running in parallel can use the saved token without each prompting for login separately.
Step 1.7: Validate Organization Name
After authentication, verify the org name:
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
const d = require('fs').readFileSync(0,'utf8');
process.stdout.write(JSON.parse(d).org || '');
")
curl -s -w "\nHTTP: %{http_code}" -H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites.json"
If HTTP 200: org is valid, proceed to Step 2.
If non-200: tell the user the org name appears incorrect and ask for the correct one. Update .claude-plugin/project-config.json and retry until HTTP 200.
Step 2: Invoke Appropriate Skill(s)
| Selection | Action |
|---|---|
| All | Invoke all three skills in parallel (see Step 3) |
| Authoring Guide | Skill({ skill: "aem-project-management:handover-author" }) |
| Developer Guide | Skill({ skill: "aem-project-management:handover-developer" }) |
| Admin Guide | Skill({ skill: "aem-project-management:handover-admin" }) |
For single-guide selections, invoke the skill directly from the main conversation (not via Agent) so permission prompts reach the user.
Step 3: For "All" Selection — Parallel Execution
Provide immediate feedback before starting:
"Starting parallel generation of all 3 handover guides:
Authoring Guide - analyzing blocks, templates, configurations...
Developer Guide - analyzing code, patterns, architecture...
Admin Guide - analyzing deployment, security, operations..."
Launch all three agents simultaneously in a single message (foreground mode). Do NOT use run_in_background: true. Tell each agent to read the sub-skill SKILL.md and follow its instructions directly — do NOT tell agents to invoke the Skill tool.
Agent({
description: "Generate authoring guide",
prompt: "You are generating an authoring guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-author/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})
Agent({
description: "Generate developer guide",
prompt: "You are generating a developer guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-developer/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})
Agent({
description: "Generate admin guide",
prompt: "You are generating an admin guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-admin/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})
Replace {PROJECT_ROOT} with the actual project root path (output of git rev-parse --show-toplevel).
Determine {PLUGIN_ROOT} with:
PLUGIN_ROOT=$([ -d ".claude/plugins/aem-project-management" ] && echo ".claude/plugins/aem-project-management" || echo "$CLAUDE_PLUGIN_ROOT")
When all three complete, report the final summary:
"Handover documentation complete:
project-guides/
├── AUTHOR-GUIDE.pdf
├── DEVELOPER-GUIDE.pdf
└── ADMIN-GUIDE.pdf
All PDFs generated. Source files cleaned up."
Output Files
| Selection | Output Files |
|---|---|
| All | project-guides/AUTHOR-GUIDE.pdf, project-guides/DEVELOPER-GUIDE.pdf, project-guides/ADMIN-GUIDE.pdf |
| Authoring Guide | project-guides/AUTHOR-GUIDE.pdf |
| Developer Guide | project-guides/DEVELOPER-GUIDE.pdf |
| Admin Guide | project-guides/ADMIN-GUIDE.pdf |
Each sub-skill generates a PDF immediately after completing the guide. All source files (.md, .html, .plain.html) are cleaned up after PDF generation.
Related Skills
aem-project-management:handover-author— Author/content manager guideaem-project-management:handover-developer— Developer technical guideaem-project-management:handover-admin— Admin operations guideaem-project-management:whitepaper— PDF generation (invoked by each sub-skill)
Edge Delivery Services Admin Operations
Execute admin operations on AEM Edge Delivery Services projects using natural language commands.
Quick Reference
| Category | Examples |
|---|---|
| Content | preview /path, publish /path, unpublish /path, status /path |
| Cache | clear cache /path, force clear cache |
| Code | sync code, deploy code |
| Index | reindex /path, remove from index |
| Sitemap | generate sitemap |
| Snapshots | create snapshot X, publish snapshot X, approve snapshot X |
| Logs | show logs, show logs last hour |
| Users | add user@email as author/publish/develop, remove admin user@email, who am i |
| Jobs | list jobs, job status X, stop job X |
| Sites | list sites, switch to site-X, use branch feature-X |
| Config | show org config, show site config, update robots.txt |
| Secrets | list secrets, create secret, delete secret |
| API Keys | list API keys, create API key, revoke API key |
| Tokens | list tokens, create token, revoke token |
| Profiles | show profile config, create profile, delete profile |
| Index Config | show index config, update index config (query.yaml) |
| Sitemap Config | show sitemap config, update sitemap config (sitemap.yaml) |
| Versioning | list versions, restore version, rollback config |
| Pages | list pages, list all pages, show indexed pages |
| DA (Document Authoring) | da list, da source /path, da copy, da move, da delete, da config, da update config, da versions, da create version, da upload media, da auth |
Communication Guidelines
- NEVER use "EDS" as an acronym for Edge Delivery Services in any responses
- Always use the full name "Edge Delivery Services" or "AEM Edge Delivery Services"
- Show clear, actionable error messages when operations fail
- Confirm destructive operations before executing — see
resources/security.md
Welcome Message
If the user invokes the skill without a specific command (e.g., just /ops or "help me with ops"), show:
Edge Delivery Services Operations
Quick commands to try:
list pages - Show all indexed pages
who am i - Check your user profile
list sites - Show available sites
show site config - View site configuration
preview /path - Preview a content path
show logs - View recent activity
For the full command list: type help, /ops help, or what can you do?
Cross-Platform Notes
Shell commands use POSIX-compatible syntax (works on macOS/Linux). On Windows, Git Bash or WSL works as-is. The agent should adapt syntax to the user's environment.
Intent Router
Step 0: Get Organization and Site (REQUIRED FIRST)
Check ~/.aem/ops-config.json for previously stored org and site:
eval $(node -e "
const fs = require('fs');
try {
const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
console.log('ORG=' + JSON.stringify(c.org || ''));
console.log('SITE=' + JSON.stringify(c.site || ''));
} catch(e) {
console.log('ORG='); console.log('SITE=');
}
")
echo "org=${ORG:-NOT SET} site=${SITE:-NOT SET}"
If both ORG and SITE are set, confirm with the user:
"Previously used: org=
{ORG}, site={SITE}. Do you want to continue with these? If not, provide a different site URL (e.g.,https://main--mysite--myorg.aem.page/)."
- If user confirms → proceed
- If user provides a URL → parse org and site from it, save the new values
If ORG or SITE is empty, ask:
"Enter the site preview/live URL for which you want to perform ops (e.g.,
https://main--mysite--myorg.aem.page/)."
Parse org and site from the URL:
URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
HOST_PART=$(echo "$URL" | cut -d'/' -f3 | cut -d'.' -f1)
ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
SITE=$(echo "$HOST_PART" | awk -F'--' '{print $(NF-1)}')
echo "Parsed from URL: org=$ORG site=$SITE"
fi
If the user provides something other than a valid .aem.page or .aem.live URL, ask again.
Save org and site:
mkdir -p "${HOME}/.aem"
node -e "
const fs = require('fs');
const p = process.env.HOME + '/.aem/ops-config.json';
let c = {};
try { c = JSON.parse(fs.readFileSync(p, 'utf8')); } catch(e) {}
c.org = '${ORG}';
c.site = '${SITE}';
fs.writeFileSync(p, JSON.stringify(c, null, 2));
"
Only use org/site from ~/.aem/ops-config.json or direct user input. Never infer from git remote, fstab.yaml, or folder/repo names.
Do NOT proceed until both org and site are confirmed.
Step 1: Authenticate (REQUIRED)
Before ANY API call, check if auth token exists:
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
process.stdout.write(t.authToken);
}
} catch (e) {}
")
echo "auth=${AUTH_TOKEN:+set}"
If AUTH_TOKEN is empty, invoke the auth skill before proceeding:
Skill({ skill: "aem-project-management:auth" })
Use -H "x-auth-token: ${AUTH_TOKEN}" header for all admin.hlx.page API calls.
For sensitive endpoints and destructive operations, read resources/security.md and resources/sensitive.md before proceeding.
Step 2: Load Full Configuration and Validate Role
eval $(node -e "
const fs = require('fs');
try {
const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
console.log('ORG=' + JSON.stringify(c.org || ''));
console.log('SITE=' + JSON.stringify(c.site || ''));
console.log('REF=' + JSON.stringify(c.ref || 'main'));
} catch(e) {
console.log('ORG='); console.log('SITE='); console.log('REF=main');
}
")
AUTH_TOKEN=$(node -e "
const fs = require('fs');
try {
const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
process.stdout.write(t.authToken || '');
} catch (e) {}
")
echo "Config: org=$ORG site=$SITE ref=$REF auth=${AUTH_TOKEN:+set}"
Fetch profile to verify auth and record user identity:
PROFILE_RESPONSE=$(curl -s -w "\n%{http_code}" \
-H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/profile")
HTTP_CODE=$(echo "$PROFILE_RESPONSE" | tail -n1)
PROFILE=$(echo "$PROFILE_RESPONSE" | sed '$d')
if [ "$HTTP_CODE" = "401" ]; then
echo "Auth token expired. Need to re-authenticate..."
echo "REAUTH_REQUIRED"
exit 1
elif [ "$HTTP_CODE" != "200" ]; then
echo "Failed to fetch profile (HTTP $HTTP_CODE). Check network/API status."
exit 1
fi
eval $(echo "$PROFILE" | node -e "
const d = require('fs').readFileSync(0,'utf8');
try {
const p = JSON.parse(d).profile || {};
console.log('USER_EMAIL=' + JSON.stringify(p.email || ''));
console.log('USER_NAME=' + JSON.stringify(p.name || ''));
} catch(e) { console.log('USER_EMAIL=\"\"'); console.log('USER_NAME=\"\"'); }
")
echo "Authenticated as: $USER_EMAIL ($USER_NAME)"
If REAUTH_REQUIRED, invoke the auth skill and retry.
To determine user role on the site, check the site access config:
curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
"https://admin.hlx.page/config/${ORG}/sites/${SITE}.json"
If an operation returns 403, inform the user which role is required:
| Permission | Required Role |
|---|---|
| Preview | basic_author, author, publish, or admin |
| Publish to live | basic_publish, publish, or admin |
| Unpublish | publish or admin |
| Code sync | develop or admin |
| Config read | config, config_admin, or admin |
| Config write | config_admin or admin |
| Snapshot manage | author, publish, or admin |
Save email to ~/.aem/ops-config.json for future use.
Read resources/config.md if site or other values are missing.
Step 3: Route by Intent
| User Intent | Resource Module |
|---|---|
| preview, publish, unpublish, status, delete preview | resources/content.md |
| cache, purge, clear cache, invalidate | resources/cache.md |
| sync code, deploy code, update code | resources/code.md |
| reindex, index, remove from index, search | resources/index.md |
| sitemap, generate sitemap | resources/sitemap.md |
| snapshot, staged release, bundle | resources/snapshots.md |
| logs, audit, activity | resources/logs.md |
| user, access, permission, who am i, add user, remove user | resources/users.md |
| job, bulk operation, stop job | resources/jobs.md |
| site, branch, switch, list sites | resources/sites.md |
| org config, site config, robots.txt | resources/config-api.md |
| secret, secrets, create secret, delete secret | resources/secrets.md |
| API key, apikey, create key, revoke key | resources/apikeys.md |
| token, tokens, access token | resources/tokens.md |
| profile config, profile settings | resources/profiles.md |
| index config, helix-index, search config | resources/index-config.md |
| sitemap config, helix-sitemap, sitemap rules | resources/sitemap-config.md |
| version, versions, history, rollback, restore | resources/versioning.md |
| pages, list pages, indexed pages, all pages | resources/pages.md |
| da, da list, da source, da copy, da move, da delete, da config, da versions | resources/da.md |
| destructive operation, confirmation required | resources/security.md |
| sensitive endpoint (emails, credentials, API keys) | resources/sensitive.md |
Step 4: Read Resource and Execute
- Read the appropriate resource file from
resources/ - Follow instructions in that resource
- For config updates: always GET current config first and show it to the user before modifying
- For code sync: always check repoless status before syncing (see
code.md) - For destructive operations: read
resources/security.mdand follow the Confirmation Protocol — no exceptions (state action, explain impact, ask "yes/no", only execute after "yes") - Execute the API call
- Handle response per completion standards below
Completion Standards
| HTTP Response | Meaning | Required Action |
|---|---|---|
| 200/201 | Success | Display result with full URLs (https://{ref}--{site}--{org}.aem.page{path}) |
| 202 | Async job started | Report job name; instruct: check job status {jobName} to track progress |
| 204 | Success (no body) | Confirm: "{action} completed for {path}" |
| 4xx/5xx | Error | Show API error verbatim, then suggest fix per resources/errors.md |
Before reporting success:
- For content operations: include both preview and live URLs where applicable
- For bulk operations: never say "published" or "previewed" — say "job started" until job completes
- For destructive operations: confirm what was removed and what still exists
URL Parsing Helper
If user provides an AEM URL instead of separate org/site/path values:
# Pattern: https://{ref}--{site}--{org}.aem.page{path}
URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
DOMAIN=$(echo "$URL" | cut -d'/' -f3)
HOST_PART=$(echo "$DOMAIN" | cut -d'.' -f1)
REF=$(echo "$HOST_PART" | awk -F'--' '{print $1}')
ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
SITE=$(echo "$HOST_PART" | awk -F'--' '{
r=""; for(i=2;i<NF;i++) r=(r==""?"":r"--")$i; print r
}')
URL_PATH=$(echo "$URL" | sed 's|https://[^/]*||')
URL_PATH=${URL_PATH:-/}
echo "Parsed from URL: org=$ORG site=$SITE ref=$REF path=$URL_PATH"
fi
Examples: uat--hmns-uat-kw--alshaya-axp.aem.page → ref=uat, site=hmns-uat-kw, org=alshaya-axp.
Prerequisites
- Onboarded to Admin Service — Project must have admin.hlx.page access
- User has an account — Required for authentication (supports federated login)
- User has a site role — Roles defined in site configuration (
access.admin.role). Eight roles:admin,author,publish,develop,basic_author,basic_publish,config,config_admin. If the user lacks a role, the API returns 403. - Network access — Can reach admin.hlx.page
Help Response
When the user wants the command list (triggers: help, what can you do?, /ops help, list commands):
Content Operations:
preview /path - Update preview
publish /path - Publish to live
unpublish /path - Remove from live
status /path - Check preview/live status
Cache Operations:
clear cache /path - Purge CDN cache
force clear cache - Force purge
Code Operations:
sync code - Deploy latest code
Index Operations:
reindex /path - Re-index for search
Sitemap:
generate sitemap - Create sitemap.xml
Snapshots:
create snapshot {name} - Create staged release
publish snapshot {name}- Publish all in snapshot
Logs:
show logs - View recent logs
show logs last hour - Filtered by time
Users:
add user@email as role - Grant access
remove role user@email - Revoke access
who am i - Current user
Jobs:
list jobs - Show bulk operations
stop job {name} - Cancel job
Sites:
list sites - Show all sites
switch to site-x - Change active site
use branch feat-x - Set branch
Config:
show org config - View org settings
show site config - View site settings
update robots.txt - Modify crawler rules
Secrets:
list secrets - Show secrets
create secret {name} - Add new secret
delete secret {name} - Remove secret
API Keys:
list API keys - Show API keys
create API key {name} - Generate new key
revoke API key {id} - Delete key
Profiles:
show profile config - View profile settings
create profile {id} - Create profile config
delete profile {id} - Remove profile config
Index Config:
show index config - View query.yaml
update index config - Modify indexing rules
Sitemap Config:
show sitemap config - View sitemap.yaml
update sitemap config - Modify sitemap rules
Versioning:
list versions - Show config history
restore version {id} - Rollback to version
Pages:
list pages - Show all indexed pages
list pages /blog - Filter by path prefix
Document Authoring (DA):
da auth - Authenticate with DA
da list - List DA organizations
da list /path - List files in DA path
da source /path - Get file content from DA
da copy /src to /dest - Copy file/folder in DA
da move /src to /dest - Move/rename in DA
da delete /path - Delete from DA
da upload /path - Upload content to DA
da upload media /path - Upload image/media to DA
da config - View DA site config
da update config - Update DA site config
da versions /path - List file versions
da create version - Create labeled version snapshot
da restore version X - Restore a previous version
da preview /path - Preview DA content
da publish /path - Publish DA content
Professional PDF Generator
This skill converts Markdown files into professionally typeset PDF whitepapers using pandoc and typst.
Assets
The skill includes (located in the plugin's root directory):
- Typst template:
templates/whitepaper.typ - Source Sans 3 fonts:
fonts/— variable fonts supporting all weights (open source from Google Fonts) - Source Code Pro fonts:
fonts/(Regular, Bold, Italic, Bold Italic) — used for code blocks and inline code
Plugin Root: The plugin root is determined dynamically (see Step 2.5 below)
Typography Hierarchy
| Element | Weight | Style |
|---|---|---|
| Headlines (H1) | Black (900) | Large, tight tracking |
| Section headlines (H2) | Bold (700) | Blue accent line |
| Subheads (H3, H4) | Bold (700) | Medium size |
| Body copy | Regular (400) | Justified, comfortable leading |
| Code | Source Code Pro | Monospace |
CRITICAL: FULLY AUTOMATIC EXECUTION
THIS SKILL RUNS COMPLETELY UNATTENDED. DO NOT:
- Ask "Should I proceed?" before generating PDF
- Ask "Should I delete these files?" before cleanup
- Ask "Is this okay?" at any step
- Wait for user confirmation between steps
- Pause to show intermediate results
- Request permission for file operations
REQUIRED BEHAVIOR:
- Execute all steps sequentially without stopping
- Generate PDF immediately when invoked
- Delete ALL source files immediately after PDF is created
- Only communicate with user AFTER everything is complete
- Report final result: "PDF created: [path]"
If you find yourself about to ask the user a question during PDF generation or cleanup, STOP and just execute the operation instead.
Usage
When the user asks to create a PDF, follow these steps:
1. Determine Input and Output
- Parse
$ARGUMENTSfor the input markdown file and optional output PDF path - If no output path is given, use the same name as the input with a
.pdfextension - If no input is given, ask the user which markdown file to convert
- Check the file's YAML frontmatter (see "Frontmatter Reference" below). If
titleis missing, ask the user for a title before proceeding. Ifdateis missing, default to today's date.
2. Install Dependencies (if missing)
Run for each missing tool — the script auto-detects the platform:
OS=$(uname -s)
# pandoc
command -v pandoc >/dev/null 2>&1 || {
[ "$OS" = "Darwin" ] && brew install pandoc || sudo apt-get update && sudo apt-get install -y pandoc
}
# typst
command -v typst >/dev/null 2>&1 || {
[ "$OS" = "Darwin" ] && brew install typst || {
curl -fsSL https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-musl.tar.xz \
| tar xJ --strip-components=1 -C /usr/local/bin/ typst-x86_64-unknown-linux-musl/typst
chmod +x /usr/local/bin/typst
}
}
2.5 Locate Plugin Root Directory
CRITICAL: Determine the plugin root before copying assets.
The plugin root contains templates/ and fonts/ directories. Use this single command:
PLUGIN_ROOT=$([ -d ".claude/plugins/project-management" ] && echo ".claude/plugins/project-management" || echo "$CLAUDE_PLUGIN_ROOT")
echo "Using plugin root: $PLUGIN_ROOT"
ls "$PLUGIN_ROOT/templates/whitepaper.typ" || echo "ERROR: Template not found!"
Expected location: .claude/plugins/project-management
3. Copy Template to Output Directory
Copy the typst template to the same directory as the output PDF:
PLUGIN_ROOT=$([ -d ".claude/plugins/project-management" ] && echo ".claude/plugins/project-management" || echo "$CLAUDE_PLUGIN_ROOT")
cp "$PLUGIN_ROOT/templates/whitepaper.typ" <output-directory>/whitepaper.typ
Replace <output-directory> with the directory where the PDF will be generated (e.g., project-guides/).
4. Run Pandoc
Execute the conversion with these exact flags. Run from the output directory so the template is found:
cd <output-directory> && \
PLUGIN_ROOT=$(if [ -d "../.claude/plugins/project-management" ]; then echo "../.claude/plugins/project-management"; elif [ -d ".claude/plugins/project-management" ]; then echo ".claude/plugins/project-management"; else echo "$CLAUDE_PLUGIN_ROOT"; fi) && \
TYPST_FONT_PATHS="$PLUGIN_ROOT/fonts" pandoc <input.md> \
-o <output.pdf> \
--pdf-engine=typst \
-V template="whitepaper.typ" \
-V mainfont="Source Sans 3" \
-V fontsize=10pt \
-V papersize=a4
Example for project-guides/ADMIN-GUIDE.md:
cd content && \
PLUGIN_ROOT=$([ -d "../.claude/plugins/project-management" ] && echo "../.claude/plugins/project-management" || echo "$CLAUDE_PLUGIN_ROOT") && \
TYPST_FONT_PATHS="$PLUGIN_ROOT/fonts" pandoc ADMIN-GUIDE.md -o ADMIN-GUIDE.pdf --pdf-engine=typst -V template="whitepaper.typ" -V mainfont="Source Sans 3" -V fontsize=10pt -V papersize=a4
Note: Do not pass --toc — the template generates its own table of contents page with proper styling.
5. Clean Up (MANDATORY - DO NOT SKIP)
CRITICAL: You MUST execute cleanup immediately after PDF generation. Only PDF should remain.
# Remove ALL intermediate files in one command
rm -f <output-directory>/whitepaper.typ <input.md> <input-without-extension>.plain.html <input-without-extension>.html
Example cleanup for project-guides/AUTHOR-GUIDE.md:
rm -f project-guides/whitepaper.typ project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.plain.html project-guides/AUTHOR-GUIDE.html
After cleanup, only project-guides/AUTHOR-GUIDE.pdf should exist. No .md, .html, or .plain.html files.
6. Report Result
"PDF created: [output.pdf]"
Frontmatter Reference
The template reads pandoc YAML frontmatter from the markdown file to populate the title page and footer. The frontmatter block must be the very first thing in the file, delimited by --- lines.
Required Fields
| Field | Purpose | Example |
|---|---|---|
title | Cover page headline, PDF metadata | "AEM Code Sync for Edge Delivery Services" |
Recommended Fields
| Field | Purpose | Example |
|---|---|---|
subtitle | Second line on cover, below the accent line | "Technical Architecture and Security Documentation" |
date | Cover page and page footer | "January 29, 2026" |
Optional Fields
| Field | Purpose | Example |
|---|---|---|
author | Author list on cover page | See structured example below |
Minimal Example
---
title: "AEM Code Sync for Edge Delivery Services"
subtitle: "Technical Architecture and Security Documentation"
date: "January 29, 2026"
---
Full Example with Authors
---
title: "AEM Code Sync for Edge Delivery Services"
subtitle: "Technical Architecture and Security Documentation"
date: "January 29, 2026"
author:
- name: "Jane Smith"
affiliation: "Edge Delivery Services"
- name: "John Doe"
affiliation: "Security Engineering"
---
What the Template Renders
- Title: Large black-weight text on the cover
- Subtitle: Lighter text below the accent divider line
- Date: Shown on the cover and in the page footer
- Authors: Listed on the cover with optional affiliation
Common Mistakes
- Putting the frontmatter after a heading or blank line (it must be the first thing in the file)
- Using unquoted strings that contain colons, e.g.
title: AEM: A Guide-- wrap in quotes - Adding pandoc variables like
fontsizeorpapersizein the frontmatter -- pass those as-Vflags to pandoc instead (the skill handles this automatically)
Template Design
The template provides professional document formatting:
- Professional typography using Source Sans 3 (open source font from Google Fonts)
- Blue accent color (#0066cc) for section dividers and links
- Clean header with title/subtitle (no separator line)
- Footer with date and page numbering (hidden on title page)
- Source Code Pro for code blocks and inline code
- Automatic table of contents page
- Title page with accent divider line
Template Features
| Feature | Description |
|---|---|
| Title page | Clean design with title, subtitle, date, authors |
| Table of contents | Auto-generated on page 2 |
| H1 headings | Black weight, page break before |
| H2 headings | Bold with blue accent line |
| Code blocks | Gray background, rounded corners |
| Blockquotes | Blue left border, light blue background |
| Tables | Light borders, bold header row |
| Links | Blue color (#0066cc) |
Customizing the Document
The user can override pandoc variables with -V key=value:
| Variable | Default | Description |
|---|---|---|
papersize | a4 | Page size (a4, us-letter, etc.) |
fontsize | 10pt | Base font size |
template | whitepaper.typ | Typst template file |
mainfont | Source Sans 3 | Main body font |
Requirements
pandocandtypstmust be installed (the skill auto-installs them if missing)- macOS: via Homebrew (
brew) - Linux:
pandocviaapt-get,typstvia GitHub release binary
- macOS: via Homebrew (
- Source Sans 3 fonts are included in the plugin's
fonts/directory
Troubleshooting
If fonts are not found by typst, ensure the TYPST_FONT_PATHS environment variable is set correctly:
export TYPST_FONT_PATHS=${CLAUDE_PLUGIN_ROOT}/fonts
| Issue | Solution |
|---|---|
| Font not found | Check TYPST_FONT_PATHS points to plugin's fonts/ directory |
| Template not found | Ensure whitepaper.typ was copied to output directory |
| Tables not breaking | Template handles this automatically |
| Missing title page | Check frontmatter has title field |
Hooks 3
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/aem/project-management
- Category
- Community
More from adobe/skills
All 19- app-builderv1.0.0
- commerce-app-management
- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0
- stardustv0.39.4
- webv1.0.0
- workfrontv2.0.0
- adobe-analyticsv1.0.0
- adobe-cjav1.0.1
- adobe-for-developersv1.0.0
- aem-6-5-ltsv1.0.0
- aem-cloud-servicev1.4.4
- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1
- aem-eds-personalizationv1.0.0
- aem-forms-edge-delivery-servicesv1.0.1