admin

プロジェクト引き継ぎ — 管理者ガイド

AEM Edge Delivery Services プロジェクトを引き継ぐ管理者向けの包括的なドキュメントを生成します。Config Service のセットアップ、権限、Admin API の操作、トラブルシューティングを含む、完全な管理者ガイドを作成します。

このスキルを使用するタイミング

• クライアント管理者へのプロジェクトの引き継ぎ
• プロジェクトの管理手順の文書化
• 運用ランブックの作成
• 「管理者ガイドを生成」
• 「管理者向けドキュメント」
• 「管理者への引き継ぎ」

---

ステップ 0：プロジェクトのルートに移動し、Edge Delivery Services プロジェクトであることを確認する（条件付き）

allGuides フラグが設定されている場合は、このステップをスキップしてください（オーケストレーターによる検証と移動がすでに完了しています）。

重要：スキップしない場合は、cd コマンドを必ず実行してください。絶対パスは使用せず、実際にディレクトリを変更してください。

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
  # Navigate to git project root (works from any subdirectory)
  cd "$(git rev-parse --show-toplevel)"
  # Verify it's an Edge Delivery Services project
  ls scripts/aem.js
fi

重要：

• 上記の cd コマンドは、Bash ツールを使用して必ず実行してください
• 以降のすべてのステップは、プロジェクトのルートから実行します
• 絶対パスを使って確認するのではなく、実際に移動してください
• ガイドは project-root/project-guides/ に作成されます

スキップせず、かつ scripts/aem.js が存在しない場合は、次のように応答してください：

「このスキルは AEM Edge Delivery Services プロジェクト向けです。現在のディレクトリは Edge Delivery Services プロジェクトではないようです（scripts/aem.js が見つかりません）。

Edge Delivery Services プロジェクトに移動してから、もう一度お試しください。」

確認に失敗した場合は停止してください。それ以外の場合は続行してください。現在、プロジェクトのルートにいます。

---

実行チェックリスト

- [ ] Phase 1: Gather Project Context
- [ ] Phase 2: Generate Admin Guide Content
- [ ] Phase 3: Customize for Project
- [ ] Phase 4: Generate Professional PDF

---

コミュニケーションに関するガイドライン

• 生成するドキュメントやチャットでの応答では、Edge Delivery Services の略語として「EDS」を絶対に使用しないでください
• 常に正式名称「Edge Delivery Services」または「AEM Edge Delivery Services」を使用してください
• これは、すべての出力ファイル（PDF、HTML、Markdown）とユーザーとのすべてのやり取りに適用されます

---

⚠️ 重要なパス要件

ファイルは必ず次の正確なパスに保存してください：

project-guides/ADMIN-GUIDE.md

ファイルを書き込む前に：

1. まず、ディレクトリを作成してください：mkdir -p project-guides
2. 次に、次の場所に書き込んでください：project-guides/ADMIN-GUIDE.md

これが重要な理由： 適切な整理と PDF 変換のため、ファイルは project-guides/ に配置する必要があります。

❌ 誤り： ADMIN-GUIDE.md（ルート） ❌ 誤り： docs/ADMIN-GUIDE.md ❌ 誤り： /workspace/ADMIN-GUIDE.md ✅ 正解： project-guides/ADMIN-GUIDE.md

---

出力形式

必須の出力： project-guides/ADMIN-GUIDE.pdf

厳禁事項：

• ❌ fstab.yaml を読んだり分析したりしないでください。ほとんどのプロジェクトには存在せず、すべてのサイトが表示されるわけでもありません
• ❌ .plain.html ファイルを作成しないでください
• ❌ convert_markdown_to_html ツールを使用しないでください。このツールはガイド全体を、表示されてはならない生のフロントマターが見える状態で HTML に変換します
• ❌ ユーザーに「Markdown を手動で PDF に変換してください」と伝えないでください
• ❌ Markdown をルートディレクトリや project-guides/ 以外の場所に保存しないでください
• ❌ 「PDF は後で生成されます」や「セッション終了時に生成されます」と言わないでください。今すぐ生成してください

HTML 出力は、Write ツールで作成する短い概要ページにしてください。 内容は次のとおりです：

• タイトルと簡単な説明
• 「内容」箇条書き
• PDF のダウンロードリンク

ガイド全体を変換した HTML にしてはいけません。

必須のワークフロー：

1. mkdir -p project-guides を実行して、ディレクトリが存在することを確認する
2. YAML フロントマター（title、date）を含む Markdown コンテンツを生成する
3. project-guides/ADMIN-GUIDE.md に保存する（例外なく正確なパスを指定）
4. 直ちに PDF 変換を実行する（フェーズ 4.1 を参照）
5. ソースファイルをすべて削除する（PDF のみ残す）
6. 最終出力：project-guides/ADMIN-GUIDE.pdf

---

フェーズ 0：組織名を取得する（最初に必須）

このスキルを実行するたびに、ユーザーが直接実行した場合（例：「管理者ガイドを生成」）も、引き継ぎフローを通じて実行した場合も、何よりも先に Config Service の組織名を取得しておく必要があります。このフェーズをスキップしないでください。

0.1 保存済みの組織名を確認する

# Check if org name is already saved
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 組織名のプロンプト（保存されていない場合）

組織名が保存されていない場合は、必ず処理を一時停止し、ユーザーに直接尋ねてください。

「Config Service の組織名を教えてください。これは Edge Delivery Services の URL における {org} の部分です（例：https://main--site--{org}.aem.page）。組織名は GitHub の組織名と異なる場合があります。」

重要なルール：

• 定義済みの選択肢を指定した AskUserQuestion は使用しないでください — 通常のテキストの質問として尋ねてください
• 組織名は必須です — 「スキップ」の選択肢を提示しないでください
• 処理を続行する前に、ユーザーが組織名を入力するまで待ってください
• 有効な組織名が入力されなかった場合は、もう一度尋ねてください

0.3 組織名を保存する

保存済みの設定またはユーザー入力から組織名を取得したら、今後のために保存してください。

# Create config directory if needed
mkdir -p .claude-plugin
# Ensure .claude-plugin is in .gitignore (contains project config)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

# Save org name to config file (create or update)
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.5：Adobe IMS で認証する

組織名を取得したら、IMS トークンを取得するために認証します。

0.5.1 既存の認証トークンを確認する

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.imsToken && t.imsTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.imsToken);
    }
  } catch (e) {}
")
IMS_EXPIRY=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(String(t.imsTokenExpiry || 0));
  } catch (e) { process.stdout.write('0'); }
")
NOW=$(date +%s)

if [ -n "$IMS_TOKEN" ] && [ "$IMS_EXPIRY" -gt "$((NOW + 60))" ]; then
  echo "Token valid (expires in $((IMS_EXPIRY - NOW)) seconds)"
else
  echo "Token missing or expired. Need to authenticate."
fi

0.5.2 認証する（有効なトークンがない場合）

有効なトークンがない場合は、認証スキルを呼び出してください。

Skill({ skill: "project-management:auth" })

次の処理が行われます。

1. Adobe ID のログイン画面をブラウザーで開きます
2. IMS OAuth トークンを自動的に取得します
3. トークンを ~/.aem/ims-token.json に保存します（ユーザーレベルで、プロジェクト間で共有されます）
4. 完了するとブラウザーを自動的に閉じます

0.5.3 認証を確認する

認証スキルの完了後、トークンが機能することを確認してください。

IMS_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.imsToken || '');
  } catch (e) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")

# Test with authenticated endpoint
curl -s -w "%{http_code}" -o /dev/null -H "Authorization: Bearer ${IMS_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites.json"

200 が返された場合、認証は成功です。401 が返された場合は、認証スキルを再実行してください。

---

フェーズ 1：プロジェクトのコンテキストを収集する

1.1 Config Service API でサイトとコードリポジトリを取得する

⚠️ 必須のデータソース — 代替手段は使用できません

Config Service API を必ず呼び出してください。サイト情報の取得元として認められるのはこれだけです。

❌ 禁止されている方法（誤った結果につながります）：

• fstab.yaml を分析する — リポジトリレスの構成では、すべてのサイトが表示されるとは限りません
• README.md を読む — 情報が古い、または不完全な場合があります
• コードベースの構造から推測する — CDN の設定や追加のサイトを見落とします
• git のリモート URL を使用する — 組織名が Config Service の組織名と異なる場合があります
• プロジェクトフォルダー名に基づいて推測する

✅ 必須：レスポンスを実行して保存する

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")

# Save response to file - Step 1.2 depends on this file
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

📁 必須の成果物： .claude-plugin/sites-config.json

API リファレンス： https://www.aem.live/docs/admin.html#tag/siteConfig/operation/getConfigSites

---

レスポンスは sites 配列を含む JSON オブジェクトです（各エントリーには name フィールドがあります）。サイト名を抽出し、サイトごとの URL を作成します。

• プレビュー： https://main--{site-name}--{org}.aem.page/
• ライブ： https://main--{site-name}--{org}.aem.live/

複数のサイトがある場合はリポジトリレス構成です。サイトが 1 つの場合は標準構成です。

続けて、コードとコンテンツの詳細を取得するため、個々のサイト設定を取得します。

IMS_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.imsToken || '');
  } catch (e) {}
")
curl -s -H "Authorization: Bearer ${IMS_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

レスポンスの例：

{
  "code": {
    "owner": "github-owner",
    "repo": "repo-name",
    "source": { "type": "github", "url": "https://github.com/owner/repo" }
  },
  "content": {
    "source": {
      "url": "https://content.da.live/org-name/site-name/",
      "type": "markup"
    }
  }
}

レスポンスから抽出する情報：

• code.owner / code.repo — GitHub リポジトリ
• content.source.url — コンテンツのマウントパス（例：https://content.da.live/org/site/）
• content.source.type — コンテンツソースの種類（markup、onedrive、google）

⚠️ fstab.yaml は使用しないでください — 代わりに Config Service API を使用してください。

1.2 コンテキストを作成する

1.1 で作成した成果物から読み取ります。

cat .claude-plugin/sites-config.json

JSON を解析してサイト名を抽出し、各サイトの設定を取得してコードリポジトリを確認します。

curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

これらの API レスポンスを使用して、サイト名、コードリポジトリ（owner/repo）、プレビュー URL、ライブ URL を含むコンテキストを作成します。サイト設定にコンテンツソース（例：content.da.live のパス）が含まれている場合は、サイトテーブルに記録します。

Admin Context:
├── Organization: {org from saved config}
├── Site(s): {site1}, {site2}, ... (from Config Service API response)
├── Setup Type: {repoless | standard} (from Config Service API)
├── Code Repo: {code.owner}/{code.repo} (from Config Service — GitHub or Cloud Manager)
├── Preview: https://main--{site}--{org}.aem.page/
├── Live: https://main--{site}--{org}.aem.live/
├── Login URL: https://admin.hlx.page/login/{org}/{site}
└── Config Service: https://admin.hlx.page/config/{org}/

---

フェーズ 2：管理ガイドを作成する

出力ファイル：project-guides/ADMIN-GUIDE.md

次の構成で管理者向けの引き継ぎドキュメントを作成します。

# [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 (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config if present] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |
| {site2} | [from site config if present] | https://main--{site2}--{org}.aem.page/ | https://main--{site2}--{org}.aem.live/ |

## Authentication

### Login

1. Open: https://admin.hlx.page/login/{org}/{site}
2. Sign in with your Adobe ID
3. Copy auth token for API operations

### Logout

```bash
curl -X POST \
  -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/logout/{org}/{site}/main"

ユーザー管理

現在のアクセス権を表示する

curl -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access.json"

ユーザーを追加する

ロール	コマンド
管理者	POST /config/{org}/sites/{site}/access/admin.json with {"users": ["email"]}
作成者	POST /config/{org}/sites/{site}/access/author.json with {"users": ["email"]}

ユーザーを削除する

curl -X DELETE \
  -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access/admin/{email}.json"

コンテンツ操作

プレビュー

操作	エンドポイント
単一ページ	POST /preview/{org}/{site}/main/{path}
一括プレビュー	POST /preview/{org}/{site}/main/*

公開

操作	エンドポイント
単一ページ	POST /live/{org}/{site}/main/{path}
一括公開	POST /live/{org}/{site}/main/*
公開取り消し	DELETE /live/{org}/{site}/main/{path}

キャッシュ

操作	エンドポイント
パスを消去	POST /cache/{org}/{site}/main/{path}
すべて消去	POST /cache/{org}/{site}/main/*

コード操作

コードを同期

curl -X POST \
  -H "Authorization: Bearer $IMS_TOKEN" \
  "https://admin.hlx.page/code/{owner}/{repo}/main"

よくあるタスク

タスク	手順
新しい管理者を追加	/config/{org}/sites/{site}/access/admin.json に POST します
サイトを再公開	/preview/{org}/{site}/main/* に POST してから、/live/{org}/{site}/main/* に POST します
すべてのキャッシュを消去	/cache/{org}/{site}/main/* に POST します
コード変更をデプロイ	/code/{owner}/{repo}/main に POST します

トラブルシューティング

問題	解決方法
401 Unauthorized	トークンの有効期限が切れています。再度ログインしてください
403 Forbidden	権限が不足しています。ロールを確認してください
404 Not Found	組織／サイト／パスのスペルを確認してください
429 Rate Limited	待ってから再試行してください
キャッシュが消去されない	forceUpdate: true を指定して試してください
コードが同期されない	手動で同期します：POST /code/{owner}/{repo}/main

---

リソース

リソース	URL
管理 API ドキュメント	https://www.aem.live/docs/admin.html
Config Service	https://www.aem.live/docs/config-service-setup

## Phase 3: Customize for Project

### 3.1 Fill in Project-Specific Values

Replace all placeholders:
- `{org}` → actual organization from Config Service API
- `{site}` → actual site name(s)
- `{owner}` → code owner from Config Service (GitHub org or Cloud Manager program)
- `{repo}` → code repo from Config Service

### 3.2 Add Multi-Site Details (if repoless)

If project has multiple sites, add a section listing all sites with their:
- Site name
- Preview URL
- Live URL
- Content source

### 3.3 Document Project-Specific Configurations

Check for and document:
- Custom headers (`/config/{org}/sites/{site}/headers.json`)
- CDN configuration
- Any project-specific admin procedures

---

## Phase 4: Convert to Professional PDF

### 4.1 Generate PDF (MANDATORY)

**THIS STEP IS NOT OPTIONAL. YOU MUST GENERATE THE PDF NOW.**

1. Save markdown to: `project-guides/ADMIN-GUIDE.md`
   - File MUST start with YAML frontmatter:
     ```yaml
     ---
     title: "[Project Name] - Admin Guide"
     date: "[Full Date - e.g., February 17, 2026]"
     ---
     ```
   - **Date format**: Always use full date with day, month, and year (e.g., "February 17, 2026"), NOT just month and year

2. **IMMEDIATELY after saving the markdown**, invoke the PDF conversion skill:

Skill({ skill: "project-management:whitepaper", args: "project-guides/ADMIN-GUIDE.md project-guides/ADMIN-GUIDE.pdf" })

3. Wait for PDF generation to complete (whitepaper skill auto-cleans source files)

**DO NOT:**
- Skip the PDF conversion step
- Tell user "PDF will be generated later" — generate it NOW

### 4.2 Deliver to User

After PDF is generated, inform the user:

"✓ 管理者ガイドが完成しました：project-guides/ADMIN-GUIDE.pdf"

---

## Output

**FINAL OUTPUT:** `project-guides/ADMIN-GUIDE.pdf`

All source files (.md, .html, .plain.html) are deleted after PDF generation. Only the PDF remains.

**Location:** `project-guides/` folder

---

## Success Criteria

**Data Source Validation (CRITICAL):**
- [ ] Config Service API was called (`https://admin.hlx.page/config/{ORG}/sites.json`)
- [ ] Site list came from API response, NOT from fstab.yaml or codebase analysis
- [ ] Code repo info came from site config API, NOT from git remote

**Content Validation:**
- [ ] All org/site values filled from Config Service API
- [ ] Login URL correct
- [ ] All API endpoints have correct org/site
- [ ] Multi-site documented (if applicable)
- [ ] Common tasks listed with correct paths

**Output Validation:**
- [ ] PDF generated successfully
- [ ] All source files cleaned up (only PDF remains)

---

## Tips

1. **Always use Config Service API** - org/site/code repo may differ from what's in the local git remote
2. **Test login URL** - Verify the login URL works before documenting
3. **List all sites** - For repoless setups, document every site
4. **Include examples** - Show actual paths from the project