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).

bash

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

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

markdown

- [ ] 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

bash

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

bash

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

bash

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

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.

bash

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:

bash

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

bash

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:

bash

cat .claude-plugin/sites-config.json

2.1 Analyze Navigation and Footer

bash

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

bash

ls -la templates/ 2>/dev/null && ls templates/

For each template, document: name, purpose, how to apply (metadata setting).

2.3 Section Styles

bash

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

bash

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

bash

ls placeholders.json 2>/dev/null

Document: location in DA, language sheets, key strings authors might need to update.

4.2 Redirects

bash

ls redirects.json 2>/dev/null

Document: location in DA, format (source → destination columns), when to use.

4.3 Bulk Metadata

bash

ls metadata.json 2>/dev/null

Document: location in DA, URL patterns, which metadata properties are set in bulk.

4.4 Other Configuration Sheets

bash

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).

markdown

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

handover-author

NPX Install

Tags

SKILL.md Content

Project Handover - Authoring

Step 0: Navigate to Project Root (CONDITIONAL)

Execution Checklist

Phase 0: Get Organization Name and Authenticate

0.1 Check for Saved Organization

0.2 Prompt for Organization Name (If Not Saved)

0.3 Save Organization Name

0.4 Check Auth Token

Phase 1: Gather Project Information

1.1 Fetch Sites via Config Service API

1.2 Check Multi-Language Support

Phase 2: Analyze Content Structure

2.1 Analyze Navigation and Footer

2.2 Identify Page Templates

2.3 Section Styles

Phase 3: Document Blocks and Templates

3.1 List and Analyze Blocks

3.2 Document Templates

3.3 DA and Block Library Paths

Phase 4: Document Configuration Sheets

4.1 Placeholders

4.2 Redirects

4.3 Bulk Metadata

4.4 Other Configuration Sheets

Phase 5: Generate Author Guide

5.1 Output File

5.2 Convert to Professional PDF

Success Criteria