handover
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseProject Handover Documentation
项目交接文档
Generate comprehensive handover documentation for Edge Delivery Services projects. This skill orchestrates the creation of guides for different audiences.
为Edge Delivery Services项目生成全面的交接文档。此技能可协调创建面向不同受众的指南。
When to Use This Skill
何时使用此技能
- "Generate project handover docs"
- "Create handover documentation"
- "Generate project guides"
- "Handover package"
- "Project documentation"
- "生成项目交接文档"
- "创建交接文档"
- "生成项目指南"
- "交接包"
- "项目文档"
Available Documentation Types
可用文档类型
| Guide | Audience | Skill |
|---|---|---|
| Authoring Guide | Content authors and content managers | |
| Developer Guide | Developers and technical team | |
| Admin Guide | Site administrators and operations | |
| 指南类型 | 受众 | 技能标识 |
|---|---|---|
| 作者指南 | 内容作者与内容管理者 | |
| 开发者指南 | 开发者与技术团队 | |
| 管理员指南 | 站点管理员与运维人员 | |
Execution Flow
执行流程
Step 0: Navigate to Project Root and Verify Edge Delivery Services Project (MANDATORY FIRST STEP)
步骤0:导航至项目根目录并验证Edge Delivery Services项目(必须首先执行)
CRITICAL: You MUST execute this command before anything else. Do NOT use absolute paths — actually change directory.
cdbash
undefined重要提示:你必须先执行此命令,再进行其他操作。请勿使用绝对路径——实际切换目录。
cdbash
undefinedNavigate to git project root (works from any subdirectory)
导航至Git项目根目录(从任何子目录均可生效)
cd "$(git rev-parse --show-toplevel)"
cd "$(git rev-parse --show-toplevel)"
Verify it's an Edge Delivery Services project
验证是否为Edge Delivery Services项目
ls scripts/aem.js
**IMPORTANT:**
- You MUST run the `cd` command above using the Bash tool
- All subsequent steps operate from project root
- Do NOT use absolute paths to verify — actually navigate
- Guides will be created at `project-root/project-guides/`
**If `scripts/aem.js` does NOT exist**, respond:
> "This skill is designed for AEM Edge Delivery Services projects. The current directory does not appear to be an Edge Delivery Services project (`scripts/aem.js` not found).
>
> Please navigate to an Edge Delivery Services project and try again."
**STOP if check fails. Otherwise proceed — you are now at project root.**
---ls scripts/aem.js
**注意事项:**
- 你必须使用Bash工具运行上述`cd`命令
- 后续所有步骤均从项目根目录执行
- 请勿使用绝对路径进行验证——实际导航至根目录
- 指南将创建在`project-root/project-guides/`路径下
**如果`scripts/aem.js`不存在**,请回复:
> "此技能专为AEM Edge Delivery Services项目设计。当前目录似乎并非Edge Delivery Services项目(未找到`scripts/aem.js`)。
>
> 请导航至Edge Delivery Services项目后重试。"
**如果检查失败,请停止操作。否则继续——你已处于项目根目录。**
---Step 0.5: Clean Up Stale Config
步骤0.5:清理陈旧配置
Remove any existing config to ensure fresh org and authentication for this project:
bash
rm -f .claude-plugin/project-config.json移除任何现有配置,确保为当前项目使用全新的组织信息与认证:
bash
rm -f .claude-plugin/project-config.jsonStep 1: Ask User for Documentation Type
步骤1:询问用户文档类型
MANDATORY: Use the tool with EXACTLY these 4 options:
AskUserQuestionjson
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
}]
})DO NOT omit any option. All 4 options MUST be presented.
必须操作: 使用工具,提供以下4个选项:
AskUserQuestionjson
AskUserQuestion({
"questions": [{
"question": "你希望生成哪种类型的交接文档?",
"header": "指南类型",
"options": [
{"label": "全部(推荐)", "description": "生成全部三类指南:作者指南、开发者指南和管理员指南"},
{"label": "作者指南", "description": "面向内容作者与管理者 - 区块、模板、发布流程"},
{"label": "开发者指南", "description": "面向开发者 - 代码库、实现方案、设计令牌"},
{"label": "管理员指南", "description": "面向站点管理员 - 权限、API操作、缓存管理"}
],
"multiSelect": false
}]
})请勿遗漏任何选项。必须展示全部4个选项。
Step 1.5: Get Organization Name (Required Before Generating Guides)
步骤1.5:获取组织名称(生成指南前必须操作)
AFTER the user selects guide type(s), but BEFORE invoking any sub-skills, ensure the organization name is available.
在用户选择指南类型之后,但在调用任何子技能之前,确保已获取组织名称。
1.5.1 Check for Saved Organization
1.5.1 检查已保存的组织信息
bash
undefinedbash
undefinedCheck if org name is already saved
检查是否已保存组织名称
cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"org"[[:space:]]:[[:space:]]"[^"]*"' | head -1
undefinedcat .claude-plugin/project-config.json 2>/dev/null | grep -o '"org"[[:space:]]:[[:space:]]"[^"]*"' | head -1
undefined1.5.2 Prompt for Organization Name (If Not Saved)
1.5.2 提示用户输入组织名称(若未保存)
If no org name is saved, you MUST pause and ask the user directly:
"What is your Config Service organization name? This is thepart of your Edge Delivery Services URLs (e.g.,{org}). The org name may differ from your GitHub organization."https://main--site--{org}.aem.page
IMPORTANT RULES:
- DO NOT use with predefined options — ask as a plain text question
AskUserQuestion - Organization name is MANDATORY — do not offer a "skip" option
- Wait for user to type the org name before proceeding
- If user doesn't provide a valid org name, ask again
如果未保存组织名称,你必须暂停操作并直接询问用户:
"你的Config Service组织名称是什么?这是Edge Delivery Services URL中的部分(例如:{org})。组织名称可能与你的GitHub组织不同。"https://main--site--{org}.aem.page
重要规则:
- 请勿使用带有预定义选项的——直接以纯文本问题询问
AskUserQuestion - 组织名称为必填项——请勿提供“跳过”选项
- 等待用户输入组织名称后再继续
- 如果用户未提供有效的组织名称,请再次询问
1.5.3 Save Organization Name
1.5.3 保存组织名称
Once you have the org name, save it so sub-skills can use it:
bash
undefined获取组织名称后,将其保存以便子技能使用:
bash
undefinedCreate config directory if needed
若需要则创建配置目录
mkdir -p .claude-plugin
mkdir -p .claude-plugin
Ensure .claude-plugin is in .gitignore (contains auth tokens)
确保.claude-plugin已添加至.gitignore(包含认证令牌)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore
Save org name to config file
将组织名称保存至配置文件
If "All" was selected, include allGuides flag to skip step 0 in sub-skills
如果用户选择“全部”,添加allGuides标志以跳过子技能中的步骤0验证
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
OR if "All (Recommended)" was selected:
或者如果用户选择“全部(推荐)”:
echo '{"org": "{ORG_NAME}", "allGuides": true}' > .claude-plugin/project-config.json
**Note:** Include `"allGuides": true` ONLY when user selected "All (Recommended)". This signals sub-skills to skip step 0 validation (orchestrator already validated).
Replace `{ORG_NAME}` with the actual organization name provided by the user.
**Why this matters:** The organization name is required by the Helix Admin API to determine if the project is repoless (multi-site). By gathering it once in the orchestrator, sub-skills running in parallel don't each need to prompt the user separately.echo '{"org": "{ORG_NAME}", "allGuides": true}' > .claude-plugin/project-config.json
**注意:** 仅当用户选择“全部(推荐)”时才添加`"allGuides": true`。这会告知子技能跳过步骤0的验证(编排器已完成验证)。
将`{ORG_NAME}`替换为用户提供的实际组织名称。
**此步骤的重要性:** 组织名称是Helix Admin API判断项目是否为无仓库(多站点)类型所必需的。通过在编排器中一次性收集该信息,并行运行的子技能无需各自单独提示用户。Step 1.6: Authenticate with Config Service (Browser Login)
步骤1.6:通过Config Service认证(浏览器登录)
AFTER saving the organization name, authenticate using Playwright browser automation.
保存组织名称后,使用Playwright浏览器自动化工具进行认证。
1.6.1 Check for Existing Auth Token
1.6.1 检查现有认证令牌
bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')bash
AUTH_TOKEN=$(cat .claude-plugin/project-config.json 2>/dev/null | grep -o '"authToken"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"authToken"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')1.6.2 Open Browser for Login (If No Token)
1.6.2 打开浏览器登录(若无令牌)
If no auth token exists, use Playwright CLI:
- Install Playwright (if needed):
bash
npx playwright --version 2>/dev/null || npm install -g playwright
npx playwright install chromium 2>/dev/null || true- Get first site name (unauthenticated):
bash
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
SITE=$(curl -s "https://admin.hlx.page/config/${ORG}/sites.json" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"name"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')- Get user acknowledgment before opening browser:
Use to ensure user is ready:
AskUserQuestionjson
AskUserQuestion({
"questions": [{
"question": "A browser window will open for authentication. After signing in, CLOSE THE BROWSER WINDOW to continue. Ready?",
"header": "Authentication Required",
"options": [
{"label": "Open Browser", "description": "I understand - open the browser for login"}
],
"multiSelect": false
}]
})After user confirms, run:
bash
mkdir -p .claude-plugin && npx playwright open --save-storage=.claude-plugin/auth-storage.json "https://admin.hlx.page/login/${ORG}/${SITE}/main"如果不存在认证令牌,使用Playwright CLI:
- 安装Playwright(若需要):
bash
npx playwright --version 2>/dev/null || npm install -g playwright
npx playwright install chromium 2>/dev/null || true- 获取首个站点名称(无需认证):
bash
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
SITE=$(curl -s "https://admin.hlx.page/config/${ORG}/sites.json" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"name"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')- 获取用户确认后再打开浏览器:
使用确保用户已准备就绪:
AskUserQuestionjson
AskUserQuestion({
"questions": [{
"question": "将打开浏览器窗口进行认证。登录完成后,请关闭浏览器窗口以继续操作。是否准备就绪?",
"header": "需要认证",
"options": [
{"label": "打开浏览器", "description": "我已了解 - 打开浏览器进行登录"}
],
"multiSelect": false
}]
})用户确认后,运行:
bash
mkdir -p .claude-plugin && npx playwright open --save-storage=.claude-plugin/auth-storage.json "https://admin.hlx.page/login/${ORG}/${SITE}/main"1.6.3 Extract and Save Auth Token
1.6.3 提取并保存认证令牌
After browser is closed, extract token from storage file:
bash
echo "Browser closed. Extracting auth token..."
AUTH_TOKEN=$(node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('.claude-plugin/auth-storage.json', 'utf8'));
const cookie = data.cookies.find(c => c.name === 'auth_token');
console.log(cookie ? cookie.value : '');
")
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
echo "{\"org\": \"${ORG}\", \"authToken\": \"${AUTH_TOKEN}\"}" > .claude-plugin/project-config.json
rm -f .claude-plugin/auth-storage.json
echo "Auth token saved."Why authenticate in orchestrator: By authenticating once here, all sub-skills running in parallel can use the saved token without each prompting for login separately.
关闭浏览器后,从存储文件中提取令牌:
bash
echo "浏览器已关闭。正在提取认证令牌..."
AUTH_TOKEN=$(node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('.claude-plugin/auth-storage.json', 'utf8'));
const cookie = data.cookies.find(c => c.name === 'auth_token');
console.log(cookie ? cookie.value : '');
")
ORG=$(cat .claude-plugin/project-config.json | grep -o '"org"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"org"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
echo "{\"org\": \"${ORG}\", \"authToken\": \"${AUTH_TOKEN}\"}" > .claude-plugin/project-config.json
rm -f .claude-plugin/auth-storage.json
echo "认证令牌已保存。"为何在编排器中进行认证: 通过在此处一次性完成认证,所有并行运行的子技能均可使用保存的令牌,无需各自单独提示用户登录。
Step 2: Invoke Appropriate Skill(s)
步骤2:调用相应的技能
Based on user selection:
| Selection | Action |
|---|---|
| All | Invoke all three skills in parallel (see Step 3) |
| Authoring Guide | |
| Developer Guide | |
| Admin Guide | |
根据用户选择执行操作:
| 用户选择 | 操作 |
|---|---|
| 全部 | 并行调用全部三个技能(见步骤3) |
| 作者指南 | |
| 开发者指南 | |
| 管理员指南 | |
Step 3: For "All" Selection
步骤3:当选择“全部”时
Execute all three guides in PARALLEL with streaming progress updates.
IMPORTANT: Provide immediate feedback to user before starting parallel execution:
"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...
You'll see progress updates as each guide moves through its phases."Launch all three skills simultaneously using parallel Agent tool calls (foreground mode):
In a SINGLE message, invoke three Agent tools in parallel. Foreground agents have full tool permissions and run concurrently:
javascript
// All three in ONE message - runs in parallel with full permissions
Agent({
description: "Generate authoring guide",
prompt: "Invoke skill project-management:authoring to generate the authoring guide PDF. Show progress as you complete each phase."
})
Agent({
description: "Generate developer guide",
prompt: "Invoke skill project-management:development to generate the developer guide PDF. Show progress as you complete each phase."
})
Agent({
description: "Generate admin guide",
prompt: "Invoke skill project-management:admin to generate the admin guide PDF. Show progress as you complete each phase."
})Why foreground agents:
- Run all 3 in parallel (~3x faster than sequential)
- Full tool permissions (Bash, Read, Write, Glob, Skill)
- Progress updates stream as each agent works
When all three complete, report final summary:
"Handover documentation complete:
project-guides/
├── AUTHOR-GUIDE.pdf (full guide for content authors)
├── DEVELOPER-GUIDE.pdf (full guide for developers)
└── ADMIN-GUIDE.pdf (full guide for administrators)
All PDFs generated. Source files cleaned up."Benefits of parallel execution:
- ~3x faster than sequential execution
- User sees continuous progress updates
- Each guide generates independently
并行执行全部三类指南,并实时更新进度。
重要提示: 在开始并行执行前,立即向用户提供反馈:
"开始并行生成全部3份交接指南:
📄 作者指南 - 分析区块、模板、配置...
📄 开发者指南 - 分析代码、模式、架构...
📄 管理员指南 - 分析部署、安全、运维...
每个指南的各阶段完成时,你将看到进度更新。"使用并行Agent工具调用(前台模式)同时启动全部三个技能:
在一条消息中,并行调用三个Agent工具。前台Agent拥有完整的工具权限并可并发运行:
javascript
// 全部三个技能在一条消息中调用 - 拥有完整权限并并行运行
Agent({
description: "生成作者指南",
prompt: "调用project-management:authoring技能生成作者指南PDF。完成每个阶段时展示进度。"
})
Agent({
description: "生成开发者指南",
prompt: "调用project-management:development技能生成开发者指南PDF。完成每个阶段时展示进度。"
})
Agent({
description: "生成管理员指南",
prompt: "调用project-management:admin技能生成管理员指南PDF。完成每个阶段时展示进度。"
})为何使用前台Agent:
- 全部3个技能并行运行(比顺序执行快约3倍)
- 拥有完整的工具权限(Bash、Read、Write、Glob、Skill)
- 每个Agent工作时会实时流式更新进度
当全部三个技能完成后,报告最终总结:
"交接文档生成完成:
project-guides/
├── AUTHOR-GUIDE.pdf(面向内容作者的完整指南)
├── DEVELOPER-GUIDE.pdf(面向开发者的完整指南)
└── ADMIN-GUIDE.pdf(面向管理员的完整指南)
所有PDF已生成。源文件已清理完毕。"并行执行的优势:
- 比顺序执行快约3倍
- 用户可看到持续的进度更新
- 每个指南独立生成
Output Files
输出文件
| Selection | Output Files |
|---|---|
| All | |
| Authoring Guide | |
| Developer Guide | |
| Admin Guide | |
Note: Each sub-skill generates a PDF only. All source files (.md, .html, .plain.html) are cleaned up after PDF generation.
| 用户选择 | 输出文件 |
|---|---|
| 全部 | |
| 作者指南 | |
| 开发者指南 | |
| 管理员指南 | |
注意: 每个子技能仅生成PDF文件。PDF生成后,所有源文件(.md、.html、.plain.html)将被清理。
⚠️ CRITICAL PATH REQUIREMENT
⚠️ 关键路径要求
ALL FILES MUST BE SAVED TO FOLDER:
project-guides/project-guides/AUTHOR-GUIDE.md
project-guides/DEVELOPER-GUIDE.md
project-guides/ADMIN-GUIDE.mdWHY THIS MATTERS: Files must be in for proper organization and PDF conversion.
project-guides/BEFORE WRITING ANY FILE: Run first.
mkdir -p project-guides所有文件必须保存至文件夹:
project-guides/project-guides/AUTHOR-GUIDE.md
project-guides/DEVELOPER-GUIDE.md
project-guides/ADMIN-GUIDE.md此要求的重要性: 文件必须存放在目录下,以确保组织规范并支持PDF转换。
project-guides/在写入任何文件之前: 先运行命令。
mkdir -p project-guidesMANDATORY RULES
必须遵守的规则
STRICTLY FORBIDDEN:
- ❌ Do NOT read or analyze — it does NOT exist in most projects and does NOT show all sites
fstab.yaml - ❌ Do NOT create files
.plain.html - ❌ Do NOT use tool
convert_markdown_to_html - ❌ Do NOT tell user to "convert markdown to PDF manually"
- ❌ Do NOT say "PDF will be generated later" — each sub-skill generates PDF immediately
- ❌ Do NOT save markdown to root directory or any path other than
project-guides/
REQUIRED:
- ✅ Run before writing any files
mkdir -p project-guides - ✅ Each sub-skill MUST save markdown to folder (EXACT PATH)
project-guides/ - ✅ Markdown files MUST have and
titlefields in frontmatterdate - ✅ Each sub-skill MUST invoke to generate PDF immediately after saving markdown
project-management:whitepaper - ✅ Each sub-skill MUST cleanup ALL source files (.md, .html, .plain.html) after PDF generation
- ✅ Final output is files ONLY in
.pdffolderproject-guides/
严格禁止:
- ❌ 请勿读取或分析——大多数项目中不存在此文件,且无法展示所有站点信息
fstab.yaml - ❌ 请勿创建文件
.plain.html - ❌ 请勿使用工具
convert_markdown_to_html - ❌ 请勿告知用户“手动将Markdown转换为PDF”
- ❌ 请勿说“稍后将生成PDF”——每个子技能会立即生成PDF
- ❌ 请勿将Markdown文件保存至根目录或以外的任何路径
project-guides/
必须执行:
- ✅ 在写入任何文件之前运行命令
mkdir -p project-guides - ✅ 每个子技能必须将Markdown文件保存至文件夹(路径必须完全符合要求)
project-guides/ - ✅ Markdown文件的前置内容中必须包含和
title字段date - ✅ 每个子技能在保存Markdown文件后必须立即调用生成PDF
project-management:whitepaper - ✅ 每个子技能在PDF生成后必须清理所有源文件(.md、.html、.plain.html)
- ✅ 最终输出仅为文件夹中的
project-guides/文件.pdf
Related Skills
相关技能
This skill invokes:
- - Author/content manager guide (generates PDF immediately)
project-management:authoring - - Developer technical guide (generates PDF immediately)
project-management:development - - Admin operations guide (generates PDF immediately)
project-management:admin - - PDF generation (invoked by each sub-skill after saving markdown)
project-management:whitepaper
此技能会调用:
- - 作者/内容管理者指南(立即生成PDF)
project-management:authoring - - 开发者技术指南(立即生成PDF)
project-management:development - - 管理员运维指南(立即生成PDF)
project-management:admin - - PDF生成(每个子技能保存Markdown后调用)
project-management:whitepaper