adobe avatar

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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.

Contents

Discovered from source

Skills 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:

APIHeaderUsage
admin.hlx.pagex-auth-token: ${AUTH_TOKEN}Preview, publish, status, code sync, jobs, logs, config
Config Servicex-auth-token: ${AUTH_TOKEN}Sites, config, secrets, API keys, profiles

Note: admin.da.live uses a separate Adobe IMS token with Authorization: Bearer header. See the DA-specific login flow in ops/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} in https://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 of https://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
}
FieldDescription
authTokenAdmin JWT from login callback
authTokenExpiryUnix 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

IssueSolution
Browser doesn't openManually open the URL printed in the terminal
"Send" button not workingCheck browser console for errors; ensure no ad-blocker is blocking localhost requests
No authToken in callbackThe helix-admin PR adding authToken to CLI login response has not yet been deployed
Token not receivedEnsure you clicked "Send" on the confirmation page before the 5-minute timeout
401 after loginToken expired, re-authenticate
403 on APIUser lacks permission for that org/site
State mismatchAnother process may have sent a rogue callback; re-run login

How It Works

  1. CLI starts a temporary HTTP server on a random localhost port
  2. Opens the user's default browser to admin.hlx.page/login/{org}/{site}/main with client_id=aem-cli and redirect_uri=http://localhost:{port}/...
  3. Admin API auto-detects IDP (Google, Microsoft, Adobe) and redirects to login
  4. User authenticates in their real browser
  5. After login, admin API shows a confirmation page with a "Send" button
  6. User clicks "Send" — browser POSTs { state, authToken } to localhost
  7. CLI validates state nonce, saves authToken to ~/.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 repository
  • content.source.url — Content mountpath
  • content.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

RoleCommand
AdminPOST /config/{org}/sites/{site}/access/admin.json with {"users": ["email"]}
AuthorPOST /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

OperationEndpoint
Preview pagePOST /preview/{org}/{site}/main/{path}
Bulk previewPOST /preview/{org}/{site}/main/*
Publish pagePOST /live/{org}/{site}/main/{path}
Bulk publishPOST /live/{org}/{site}/main/*
UnpublishDELETE /live/{org}/{site}/main/{path}
Purge cachePOST /cache/{org}/{site}/main/{path}
Purge allPOST /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

TaskSteps
Add new adminPOST to /config/{org}/sites/{site}/access/admin.json
Republish sitePOST /preview/{org}/{site}/main/* then /live/{org}/{site}/main/*
Clear all cachePOST to /cache/{org}/{site}/main/*
Deploy code changesPOST to /code/{owner}/{repo}/main

Troubleshooting

IssueSolution
401 UnauthorizedToken expired — login again
403 ForbiddenInsufficient permissions — check role
404 Not FoundCheck org/site/path spelling
429 Rate LimitedWait and retry
Cache not clearingTry with forceUpdate: true
Code not syncingManual sync: POST to /code/{owner}/{repo}/main

Resources

ResourceURL
Admin API Docshttps://www.aem.live/docs/admin.html
Config Servicehttps://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

CategoryCheck
Data SourceConfig Service API called (https://admin.hlx.page/config/{ORG}/sites.json)
Data SourceSite list from API response, not fstab.yaml or codebase analysis
Data SourceCode repo info from site config API, not git remote
ContentAll org/site values filled from Config Service API
ContentLogin URL correct
ContentAll API endpoints have correct org/site
ContentMulti-site documented (if applicable)
ContentCommon tasks listed with correct paths
OutputPDF generated at project-guides/ADMIN-GUIDE.pdf
OutputAll 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 repository
  • content.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

CategoryCheck
Data SourceConfig Service API called (https://admin.hlx.page/config/{ORG}/sites.json)
Data SourceSite list from API response, not fstab.yaml or codebase analysis
Data SourceDA/Block Library URLs derived from Config Service content source, not assumed from code.owner/repo
ContentQuick Reference table with all project URLs
ContentAll blocks documented in table format
ContentAll templates documented with required metadata
ContentConfiguration sheets documented
ContentPublishing workflow explained
ContentCommon tasks documented
ContentSection/page metadata options listed
ContentTroubleshooting included
OutputPDF generated at project-guides/AUTHOR-GUIDE.pdf
OutputAll 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 HistoryAction
Only "Initial commit"Skip — boilerplate default, never worked on
Only aem-aemy[bot] commitsSkip — auto-generated
Multiple commits by teamDocument — 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:

PatternWhat to Document
import statementsWhat it imports from aem.js and utils.js
loadEager / loadLazyAny custom logic added to E-L-D phases
buildAutoBlocksAuto-blocking logic
loadTemplate / template handlingTemplate system
getLanguage / language detectionMulti-language setup
getSiteRoot / site detectionMulti-site configuration
External script loadingWhich 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:

FieldWhat to Record
NameBlock folder name
PurposeWhat it does
DOM InputExpected HTML structure from CMS
DOM OutputTransformed structure after decoration
VariantsCSS classes that modify behavior
DependenciesExternal 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

CategoryCheck
Data SourceConfig Service API called (https://admin.hlx.page/config/{ORG}/sites.json)
Data SourceSite list from API response, not fstab.yaml or codebase analysis
Data SourceRepoless/standard determination from Config Service, not inferred from code
ContentQuick Reference with all project URLs
ContentArchitecture overview accurate to project
ContentDesign system fully documented (tokens, fonts, breakpoints)
ContentProject-specific blocks documented
ContentCustom scripts.js functions documented
ContentDelayed-phase integrations documented (consented.js or delayed.js)
ContentTemplates documented (if applicable)
ContentLocal development setup verified
ContentCommon tasks have clear instructions
ContentTroubleshooting section covers common issues
OutputPDF generated at project-guides/DEVELOPER-GUIDE.pdf
OutputAll 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

GuideAudienceSkill
Authoring GuideContent authors and content managershandover-author
Developer GuideDevelopers and technical teamhandover-developer
Admin GuideSite administrators and operationshandover-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)

SelectionAction
AllInvoke all three skills in parallel (see Step 3)
Authoring GuideSkill({ skill: "aem-project-management:handover-author" })
Developer GuideSkill({ skill: "aem-project-management:handover-developer" })
Admin GuideSkill({ 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

SelectionOutput Files
Allproject-guides/AUTHOR-GUIDE.pdf, project-guides/DEVELOPER-GUIDE.pdf, project-guides/ADMIN-GUIDE.pdf
Authoring Guideproject-guides/AUTHOR-GUIDE.pdf
Developer Guideproject-guides/DEVELOPER-GUIDE.pdf
Admin Guideproject-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 guide
  • aem-project-management:handover-developer — Developer technical guide
  • aem-project-management:handover-admin — Admin operations guide
  • aem-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

CategoryExamples
Contentpreview /path, publish /path, unpublish /path, status /path
Cacheclear cache /path, force clear cache
Codesync code, deploy code
Indexreindex /path, remove from index
Sitemapgenerate sitemap
Snapshotscreate snapshot X, publish snapshot X, approve snapshot X
Logsshow logs, show logs last hour
Usersadd user@email as author/publish/develop, remove admin user@email, who am i
Jobslist jobs, job status X, stop job X
Siteslist sites, switch to site-X, use branch feature-X
Configshow org config, show site config, update robots.txt
Secretslist secrets, create secret, delete secret
API Keyslist API keys, create API key, revoke API key
Tokenslist tokens, create token, revoke token
Profilesshow profile config, create profile, delete profile
Index Configshow index config, update index config (query.yaml)
Sitemap Configshow sitemap config, update sitemap config (sitemap.yaml)
Versioninglist versions, restore version, rollback config
Pageslist 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:

PermissionRequired Role
Previewbasic_author, author, publish, or admin
Publish to livebasic_publish, publish, or admin
Unpublishpublish or admin
Code syncdevelop or admin
Config readconfig, config_admin, or admin
Config writeconfig_admin or admin
Snapshot manageauthor, 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 IntentResource Module
preview, publish, unpublish, status, delete previewresources/content.md
cache, purge, clear cache, invalidateresources/cache.md
sync code, deploy code, update coderesources/code.md
reindex, index, remove from index, searchresources/index.md
sitemap, generate sitemapresources/sitemap.md
snapshot, staged release, bundleresources/snapshots.md
logs, audit, activityresources/logs.md
user, access, permission, who am i, add user, remove userresources/users.md
job, bulk operation, stop jobresources/jobs.md
site, branch, switch, list sitesresources/sites.md
org config, site config, robots.txtresources/config-api.md
secret, secrets, create secret, delete secretresources/secrets.md
API key, apikey, create key, revoke keyresources/apikeys.md
token, tokens, access tokenresources/tokens.md
profile config, profile settingsresources/profiles.md
index config, helix-index, search configresources/index-config.md
sitemap config, helix-sitemap, sitemap rulesresources/sitemap-config.md
version, versions, history, rollback, restoreresources/versioning.md
pages, list pages, indexed pages, all pagesresources/pages.md
da, da list, da source, da copy, da move, da delete, da config, da versionsresources/da.md
destructive operation, confirmation requiredresources/security.md
sensitive endpoint (emails, credentials, API keys)resources/sensitive.md

Step 4: Read Resource and Execute

  1. Read the appropriate resource file from resources/
  2. Follow instructions in that resource
  3. For config updates: always GET current config first and show it to the user before modifying
  4. For code sync: always check repoless status before syncing (see code.md)
  5. For destructive operations: read resources/security.md and follow the Confirmation Protocol — no exceptions (state action, explain impact, ask "yes/no", only execute after "yes")
  6. Execute the API call
  7. Handle response per completion standards below

Completion Standards

HTTP ResponseMeaningRequired Action
200/201SuccessDisplay result with full URLs (https://{ref}--{site}--{org}.aem.page{path})
202Async job startedReport job name; instruct: check job status {jobName} to track progress
204Success (no body)Confirm: "{action} completed for {path}"
4xx/5xxErrorShow 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

  1. Onboarded to Admin Service — Project must have admin.hlx.page access
  2. User has an account — Required for authentication (supports federated login)
  3. 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.
  4. 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

ElementWeightStyle
Headlines (H1)Black (900)Large, tight tracking
Section headlines (H2)Bold (700)Blue accent line
Subheads (H3, H4)Bold (700)Medium size
Body copyRegular (400)Justified, comfortable leading
CodeSource Code ProMonospace

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 $ARGUMENTS for the input markdown file and optional output PDF path
  • If no output path is given, use the same name as the input with a .pdf extension
  • If no input is given, ask the user which markdown file to convert
  • Check the file's YAML frontmatter (see "Frontmatter Reference" below). If title is missing, ask the user for a title before proceeding. If date is 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

FieldPurposeExample
titleCover page headline, PDF metadata"AEM Code Sync for Edge Delivery Services"

Recommended Fields

FieldPurposeExample
subtitleSecond line on cover, below the accent line"Technical Architecture and Security Documentation"
dateCover page and page footer"January 29, 2026"

Optional Fields

FieldPurposeExample
authorAuthor list on cover pageSee 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 fontsize or papersize in the frontmatter -- pass those as -V flags 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

FeatureDescription
Title pageClean design with title, subtitle, date, authors
Table of contentsAuto-generated on page 2
H1 headingsBlack weight, page break before
H2 headingsBold with blue accent line
Code blocksGray background, rounded corners
BlockquotesBlue left border, light blue background
TablesLight borders, bold header row
LinksBlue color (#0066cc)

Customizing the Document

The user can override pandoc variables with -V key=value:

VariableDefaultDescription
papersizea4Page size (a4, us-letter, etc.)
fontsize10ptBase font size
templatewhitepaper.typTypst template file
mainfontSource Sans 3Main body font

Requirements

  • pandoc and typst must be installed (the skill auto-installs them if missing)
    • macOS: via Homebrew (brew)
    • Linux: pandoc via apt-get, typst via GitHub release binary
  • 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
IssueSolution
Font not foundCheck TYPST_FONT_PATHS points to plugin's fonts/ directory
Template not foundEnsure whitepaper.typ was copied to output directory
Tables not breakingTemplate handles this automatically
Missing title pageCheck frontmatter has title field

Sponsors

Details

Marketplace
adobe/skills
Source
plugins/aem/project-management
Category
Community

More from adobe/skills

All 19