handover-author

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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)

步骤0:导航到项目根目录(可选)

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

如果
.claude-plugin/project-config.json
中已设置
allGuides
(编排器已验证),则跳过此步骤。
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
不存在,请告知用户此技能需要AEM Edge Delivery Services项目并终止流程。
后续所有步骤均从项目根目录执行。指南将创建在
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

markdown
- [ ] 阶段0:获取组织名称并完成认证
- [ ] 阶段1:从Config Service API收集项目信息
- [ ] 阶段2:分析内容结构
- [ ] 阶段3:记录区块和模板
- [ ] 阶段4:记录配置表
- [ ] 阶段5:生成PDF

Phase 0: Get Organization Name and Authenticate

阶段0:获取组织名称并完成认证

0.1 Check for Saved Organization

0.1 检查已保存的组织信息

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) {}
"
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)

0.2 提示用户输入组织名称(未保存时)

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.
如果未找到组织名称,请询问用户:
"你的Config Service组织名称是什么?这是Edge Delivery Services URL中的
{org}
部分(例如:
https://main--site--{org}.aem.page
)。组织名称可能与你的GitHub组织名称不同。"
以纯文本问题形式询问——不要使用带选项的
AskUserQuestion
。组织名称为必填项。

0.3 Save Organization Name

0.3 保存组织名称

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.
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
{ORG_NAME}
替换为实际的组织名称。

0.4 Check Auth Token

0.4 检查认证令牌

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
If
AUTH_REQUIRED
, invoke the auth skill before proceeding:
Skill({ skill: "aem-project-management:auth" })

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
,请先调用认证技能再继续:
Skill({ skill: "aem-project-management:auth" })

Phase 1: Gather Project Information

阶段1:收集项目信息

1.1 Fetch Sites via Config Service API

1.1 通过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.
Config Service API是获取站点信息的唯一可靠来源。请勿使用
fstab.yaml
、README或Git远程URL。
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(', '));
"
如果验证失败,请确认组织名称正确,重新认证后重试。
获取每个站点的配置以获取内容详情:
bash
curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
提取以下信息:
  • code.owner
    /
    code.repo
    — GitHub仓库
  • content.source.url
    — 内容挂载路径(例如:
    https://content.da.live/org/site/
  • content.source.type
    — 内容源类型(markup、onedrive、google)
根据内容源构建DA和区块库URL:
  • DA URL:
    https://da.live/#/{org}/{site}/
  • 区块库:
    https://da.live/#/{org}/{site}/.da/library
多站点 = 无仓库设置。单站点 = 标准设置。

1.2 Check Multi-Language Support

1.2 检查多语言支持

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.

bash
ls -la /en /fr /de /es /it 2>/dev/null || echo "Check DA for language folders"
记录项目是否支持多语言以及支持哪些语言。

Phase 2: Analyze Content Structure

阶段2:分析内容结构

Read site config from Phase 1:
bash
cat .claude-plugin/sites-config.json
读取阶段1中的站点配置:
bash
cat .claude-plugin/sites-config.json

2.1 Analyze Navigation and Footer

2.1 分析导航和页脚

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.
bash
ls nav.md footer.md 2>/dev/null || echo "Nav/footer likely in DA"
记录:导航和页脚的位置(DA路径或本地文件)、菜单结构、移动端表现。

2.2 Identify Page Templates

2.2 识别页面模板

bash
ls -la templates/ 2>/dev/null && ls templates/
For each template, document: name, purpose, how to apply (metadata setting).
bash
ls -la templates/ 2>/dev/null && ls templates/
针对每个模板,记录:名称、用途、应用方式(元数据设置)。

2.3 Section Styles

2.3 区块样式

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.

bash
grep -E "\.section\." styles/styles.css 2>/dev/null | head -15
记录可用的区块样式(例如:dark、highlight、narrow),用于指南中的“可用区块样式”表格。

Phase 3: Document Blocks and Templates

阶段3:记录区块和模板

3.1 List and Analyze Blocks

3.1 列出并分析区块

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.
bash
ls blocks/
静默运行区块分析。针对每个区块确定:用途、变体(来自CSS
.blockname.variant
)、作者应何时使用它。记录所有区块,以便作者了解可用资源。

3.2 Document Templates

3.2 记录模板

For each template found in Phase 2.2, document: name, purpose, required metadata fields, and how to apply (
template: name
in Metadata block).
针对阶段2.2中找到的每个模板,记录:名称、用途、必填元数据字段、应用方式(在Metadata区块中设置
template: name
)。

3.3 DA and Block Library Paths

3.3 DA和区块库路径

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.

从Config Service站点配置中获取内容路径。区块库URL为
https://da.live/#/{content-owner}/{content-path}/.da/library
——路径因项目而异。

Phase 4: Document Configuration Sheets

阶段4:记录配置表

4.1 Placeholders

4.1 占位符

bash
ls placeholders.json 2>/dev/null
Document: location in DA, language sheets, key strings authors might need to update.
bash
ls placeholders.json 2>/dev/null
记录:在DA中的位置、语言表、作者可能需要更新的关键字符串。

4.2 Redirects

4.2 重定向

bash
ls redirects.json 2>/dev/null
Document: location in DA, format (source → destination columns), when to use.
bash
ls redirects.json 2>/dev/null
记录:在DA中的位置、格式(源→目标列)、使用场景。

4.3 Bulk Metadata

4.3 批量元数据

bash
ls metadata.json 2>/dev/null
Document: location in DA, URL patterns, which metadata properties are set in bulk.
bash
ls metadata.json 2>/dev/null
记录:在DA中的位置、URL模式、批量设置的元数据属性。

4.4 Other Configuration Sheets

4.4 其他配置表

bash
ls -la *.xlsx *.json 2>/dev/null | grep -v package

bash
ls -la *.xlsx *.json 2>/dev/null | grep -v package

Phase 5: Generate Author Guide

阶段5:生成创作指南

5.1 Output File

5.1 输出文件

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-guides/AUTHOR-GUIDE.md
(先运行
mkdir -p project-guides
)。
markdown
---
title: "[项目名称] - 创作指南"
date: "[完整日期 — 例如:2026年2月17日]"
---

[Project Name] - Author Guide

[项目名称] - 创作指南

Quick Reference

快速参考

(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.)
(内容路径来自Config Service站点配置 — 例如:
content.da.live/org/site/
→ 在
#/
后使用
org/site
作为路径。路径因项目而异。)

Sites

站点

SiteContent Source (DA)PreviewLive
{site1}[from site config]https://main--{site1}--{org}.aem.page/https://main--{site1}--{org}.aem.live/
站点内容源(DA)预览正式环境
{site1}[来自站点配置]https://main--{site1}--{org}.aem.page/https://main--{site1}--{org}.aem.live/

Getting Started

入门指南

Access Requirements

访问要求

  • DA access (request from admin)
  • Preview/publish permissions
  • DA访问权限(向管理员申请)
  • 预览/发布权限

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
  1. 访问DA:[链接]
  2. 导航到正确的文件夹
  3. 创建新文档
  4. 从侧边栏的库中选择区块
  5. 在底部添加Metadata区块
  6. 预览 → 发布

Content Organization

内容组织

Site Structure

站点结构

[Describe the folder structure in DA]
[描述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.
WhatDetails
Open in DAUse the Library icon in the DA editor sidebar, or go directly to:
https://da.live/#/{content-owner}/{content-path}/.da/library
How to useClick a block or template in the library to insert it at the cursor position
区块库是文档创作工具(DA)侧边栏中的功能,用于浏览和插入区块与模板。
说明详情
在DA中打开使用DA编辑器侧边栏中的库图标,或直接访问:
https://da.live/#/{content-owner}/{content-path}/.da/library
使用方法点击库中的区块或模板,将其插入到光标位置

Available Blocks

可用区块

BlockPurposeVariantsUsage
[name][what it's for][variant1, variant2][when to use]
[Generate table rows for all blocks]
区块用途变体使用场景
[名称][用途描述][变体1, 变体2][使用时机]
[为所有区块生成表格行]

Page Templates

页面模板

TemplatePurposeRequired MetadataHow to Apply
[name][what type of pages][key fields]
template: [name]
in Metadata
[Generate table rows for all templates]
模板用途必填元数据应用方式
[名称][适用页面类型][关键字段]在Metadata中设置
template: [名称]
[为所有模板生成表格行]

Configuration Sheets

配置表

SheetLocationPurposeWhen to Update
Placeholders
/placeholders
Reusable text strings, translationsChanging labels, button text
Redirects
/redirects
Forward old URLs to new URLsAfter deleting/moving pages
Bulk Metadata
/metadata
Apply metadata to multiple pagesSetting defaults by folder
表格位置用途更新时机
占位符
/placeholders
可复用文本字符串、翻译内容修改标签、按钮文本时
重定向
/redirects
将旧URL转发到新URL删除/移动页面后
批量元数据
/metadata
为多个页面应用元数据按文件夹设置默认值时

Publishing Workflow

发布工作流

EnvironmentDomainPurpose
Preview
.aem.page
Test changes before going live
Live
.aem.live
Production site
Workflow: Edit in DA → Preview → Publish → Live immediately
环境域名用途
预览
.aem.page
上线前测试变更
正式环境
.aem.live
生产站点
工作流: 在DA中编辑 → 预览 → 发布 → 立即上线

Common Tasks

常见任务

TaskSteps
Create a PageNavigate to folder → New → Document → Add content → Add Metadata → Preview → Publish
Edit a PageOpen in DA → Make changes → Preview → Publish
Delete a PageAdd redirect first → Delete document → Publish redirects
Update NavigationEdit
/nav
document → Preview → Publish
Update FooterEdit
/footer
document → Preview → Publish
任务步骤
创建页面导航到文件夹 → 新建 → 文档 → 添加内容 → 添加Metadata → 预览 → 发布
编辑页面在DA中打开 → 修改内容 → 预览 → 发布
删除页面先添加重定向 → 删除文档 → 发布重定向规则
更新导航编辑
/nav
文档 → 预览 → 发布
更新页脚编辑
/footer
文档 → 预览 → 发布

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:
StyleEffect
[List project-specific styles]
区块用于将内容分组。使用水平分隔线(
---
)创建区块。
在区块末尾添加区块元数据区块来设置样式:
区块元数据
style[样式名称]
可用区块样式:
样式效果
[列出项目特定样式]

Page Metadata

页面元数据

PropertyRequiredPurposeExample
title
YesPage title for SEO"About Us"
description
YesSEO description"Learn about..."
image
NoSocial sharing image/images/og.jpg
template
NoApply page templateproject-article
[Add project-specific fields]
属性必填用途示例
title
SEO页面标题"关于我们"
description
SEO描述"了解我们的..."
image
社交分享图片/images/og.jpg
template
应用页面模板project-article
[添加项目特定字段]

Images and Media

图片与媒体

MethodHow
Drag & dropDrag images directly into DA editor
AEM AssetsUse Assets sidebar in DA
Best practices: descriptive filenames, always add alt text, images auto-optimized.
方法操作步骤
拖拽将图片直接拖拽到DA编辑器中
AEM Assets使用DA中的Assets侧边栏
最佳实践:使用描述性文件名、始终添加替代文本、图片会自动优化。

Troubleshooting

故障排除

IssueSolution
Page not updating after publishWait 1-2 min for cache, hard refresh (Cmd+Shift+R)
Block not displaying correctlyCheck structure matches expected format, verify variant spelling
Images not showingVerify image uploaded to DA, check path is correct
Wrong template stylingCheck
template
value in Metadata matches template name exactly
问题解决方案
发布后页面未更新等待1-2分钟缓存刷新,强制刷新页面(Cmd+Shift+R)
区块显示异常检查结构是否符合预期格式,验证变体拼写是否正确
图片不显示确认图片已上传到DA,检查路径是否正确
模板样式错误检查Metadata中的
template
值与模板名称是否完全匹配

Resources

资源

Support Contacts

支持联系人

[Add project-specific contacts]
undefined
[添加项目特定联系人]
undefined

5.2 Convert to Professional PDF

5.2 转换为专业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"

将完成的Markdown文件保存到
project-guides/AUTHOR-GUIDE.md
,并添加YAML前置内容(标题、完整日期格式,例如:"2026年2月17日")。然后立即调用PDF转换技能:
Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.pdf" })
白皮书技能会自动清理源文件。最终输出:
project-guides/AUTHOR-GUIDE.pdf
告知用户:"创作指南已完成: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.
类别检查项
数据源已调用Config Service API (
https://admin.hlx.page/config/{ORG}/sites.json
)
数据源站点列表来自API响应,而非fstab.yaml或代码库分析
数据源DA/区块库URL由Config Service内容源推导而来,而非从code.owner/repo推测
内容包含所有项目URL的快速参考表格
内容所有区块以表格形式记录
内容所有模板均记录了必填元数据
内容配置表已记录
内容发布工作流已说明
内容常见任务已记录
内容区块/页面元数据选项已列出
内容包含故障排除部分
输出PDF已生成在
project-guides/AUTHOR-GUIDE.pdf
输出所有源文件已清理(仅保留PDF)

沟通规范: 切勿使用缩写"EDS"——在所有输出和文档中始终使用"Edge Delivery Services"或"AEM Edge Delivery Services"。