/handover-author

name: handover-author
description: Generate comprehensive documentation for content authors taking over an AEM Edge Delivery Services project. Use when onboarding content authors, training content managers, or creating author-focused handover documentation — analyzes project structure and produces a complete authoring guide with blocks, templates, configurations, and publishing workflows.
license: Apache-2.0
allowed-tools: Read, Write, Edit, Bash, Skill, Glob, Grep
metadata:
  version: "1.0.0"

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 settin