authoring

プロジェクト引き継ぎ - コンテンツ作成

コンテンツ作成者とコンテンツ管理者向けの包括的なガイドを作成します。このスキルはプロジェクトを分析し、実践的なドキュメントを作成します。

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

• 新しいプロジェクトでコンテンツ作成者をオンボーディングするとき
• コンテンツ管理者をトレーニングするとき
• クライアントのコンテンツ作成チームにプロジェクトを引き継ぐとき
• コンテンツ作成者向けのドキュメントを作成するとき

---

ステップ 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

重要：

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

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

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

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

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

---

コミュニケーションのガイドライン

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

---

⚠️ 必須の保存先パス

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

project-guides/AUTHOR-GUIDE.md

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

1. まず、ディレクトリを作成します：mkdir -p project-guides
2. 次に、project-guides/AUTHOR-GUIDE.md に書き込みます

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

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

---

出力形式

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

厳禁：

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

必須のワークフロー：

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

---

実行チェックリスト

- [ ] Phase 1: Gather Project Information
- [ ] Phase 2: Analyze Content Structure
- [ ] Phase 3: Document Blocks and Templates
- [ ] Phase 4: Document Configuration Sheets
- [ ] Phase 5: Generate Professional 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} をユーザーが指定した実際の組織名に置き換えてください。

---

フェーズ 1：プロジェクト情報を収集する

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

⚠️ 必須のデータソース — 代替手段は禁止

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

❌ 禁止されている方法（不正確な結果になります）：

• fstab.yaml を分析する — repoless 構成では、すべてのサイトが表示されるわけではありません
• 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 - Phase 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/

複数のサイトがある場合は repoless 構成です。サイトが 1 つの場合は standard 構成です。

次に、コードとコンテンツの詳細を確認するため、各サイトの設定を取得してください。

まず、有効な認証トークンがあるか確認します。

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

if [ -z "$IMS_TOKEN" ]; then
  echo "AUTH_REQUIRED"
fi

AUTH_REQUIRED の場合は、先に進む前に認証スキルを呼び出してください。

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

次に、サイト設定を取得します。

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"
    },
    "contentBusId": "..."
  }
}

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

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

コンテンツソースから URL を作成する：

• DA URL： https://da.live/#/{org}/{site}/（content.source.url から導出）
• Block Library： https://da.live/#/{org}/{site}/.da/library

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

1.2 多言語対応を確認する

# Check for language folders in content structure
ls -la /en /fr /de /es /it 2>/dev/null || echo "Check DA for language folders"

出力： プロジェクトが多言語対応かどうか、および対応言語を記録します。

---

フェーズ 2：コンテンツ構造を分析する

フェーズ 1 のサイト設定を読み取ります。

cat .claude-plugin/sites-config.json

2.1 ナビゲーションとフッターを分析する

ls nav.md footer.md 2>/dev/null || echo "Nav/footer likely in DA"

記録する内容： ナビゲーションとフッターの場所（DA パスまたはローカルファイル）、メニュー構造、モバイルでの動作。

2.2 ページテンプレートを特定する

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

テンプレートがある場合は、それぞれについて記録します。 テンプレート名、用途、適用方法（メタデータ設定）。

2.3 セクションスタイル（ガイド用）

grep -E "\.section\." styles/styles.css 2>/dev/null | head -15

記録する内容： ガイドの「利用可能なセクションスタイル」テーブルに掲載する、利用可能なセクションスタイル（例：dark、highlight、narrow）。

---

フェーズ 3：ブロックとテンプレートを記録する

3.1 ブロックを一覧表示して分析する

ls blocks/

ブロックの分析は、出力せずに実行してください。 各ブロックについて、用途、バリエーション（例：CSS の .blockname.variant）、および作成者が使用するタイミングを特定します。作成者が利用可能なものを把握できるよう、プロジェクト内のすべてのブロックを記録してください。

3.2 テンプレートを記録する

フェーズ 2.2 で特定した各テンプレートについて、名前、用途、必須のメタデータフィールド、および適用方法（Metadata ブロックで template: name を指定）を記録します。

3.3 DA とブロックライブラリのパス

Config Service のサイト設定（コンテンツソース）からコンテンツパスを取得します。ブロックライブラリの URL は https://da.live/#/{content-owner}/{content-path}/.da/library です。パスはプロジェクトによって異なります。ライブラリに表示されるブロック／テンプレートを記録します。

---

フェーズ 4：設定シートを文書化する

4.1 プレースホルダー

場所： DA の /placeholders（または /placeholders.xlsx）

ls placeholders.json 2>/dev/null

文書化する項目：

項目	説明
場所	DA でプレースホルダーを確認できる場所
言語	存在する言語シート（en、fr など）
主要な文字列	作成者が更新する必要がある可能性のある重要なプレースホルダー

4.2 リダイレクト

場所： DA の /redirects（または /redirects.xlsx）

ls redirects.json 2>/dev/null

文書化する項目：

項目	説明
場所	DA でリダイレクトを確認できる場所
形式	変換元列 → 変換先列
使用する場面	URL の変更、削除されたページ、名前が変更されたページ

4.3 一括メタデータ

場所： DA の /metadata（または /metadata.xlsx）

ls metadata.json 2>/dev/null

文書化する項目：

項目	説明
場所	DA で一括メタデータを確認できる場所
パターン	使用される URL パターン（例：/news/*）
プロパティ	一括設定されるメタデータプロパティ

4.4 その他の設定シート

プロジェクト固有の設定シートがないか確認します。

# Look for other Excel/JSON config files
ls -la *.xlsx *.json 2>/dev/null | grep -v package

---

フェーズ 5：作成者向けガイドを生成する

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

# [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 source like `content.da.live/org/site/` → use `org/site` for the path after `#/`. This can differ per project; do not use code.owner/code.repo unless the API explicitly maps them.)

### Sites

| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |

(One row per site from Config Service. **Content Source (DA)** is the content path for that site — use it to build DA and Block Library URLs: `https://da.live/#/{path-from-content-source}/` and `.../.da/library`. Path format varies by project, e.g. `audemars-piguet/arbres-fondationsaudemarspiguet`.)

## 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 into your document.

| What | Details |
|------|---------|
| **Open in DA** | Use the Library icon in the DA editor sidebar, or go directly to the Block Library URL (from Config Service content path for this project): `https://da.live/#/{content-owner}/{content-path}/.da/library` |
| **What's in it** | All blocks and templates listed in the "Available Blocks" and "Page Templates" sections below appear in the library |
| **How to use** | Click a block or template in the library to insert it at the cursor position in your document |

When creating or editing a page, use the Library sidebar to add blocks instead of typing block names manually.

## 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 Section Metadata block at end of section:

| Section Metadata |        |
|------------------|--------|
| style            | [style-name] |

**Available Section Styles:**

| Style | Effect |
|-------|--------|
| [List project-specific styles in table format] |

## 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, ensure it 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 プロフェッショナルな PDF に変換する（必須）

この手順は省略できません。今すぐ PDF を生成してください。

1. Markdown を次の場所に保存します：project-guides/AUTHOR-GUIDE.md

   • ファイルは YAML フロントマターで始める必要があります：

     ---
     title: "[Project Name] - Author Guide"
     date: "[Full Date - e.g., February 17, 2026]"
     ---
     

   • 日付の形式：月と年だけではなく、必ず日、月、年を含む完全な日付を使用してください（例：「February 17, 2026」）。

2. Markdown を保存した直後に、PDF 変換スキルを呼び出します。

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

3. PDF の生成が完了するまで待ちます（whitepaper スキルがソースファイルを自動的に削除します）。

次のことは禁止します：

• PDF 変換手順を省略する
• 「PDF は後で生成されます」とユーザーに伝える — 今すぐ生成してください

5.3 ユーザーに納品する

PDF の生成後、ユーザーに知らせます。

"✓ Author guide complete: project-guides/AUTHOR-GUIDE.pdf"

---

出力

最終出力： project-guides/AUTHOR-GUIDE.pdf

PDF 生成後、すべてのソースファイル（.md、.html、.plain.html）が削除されます。PDF のみが残ります。

場所： project-guides/ フォルダー

---

成功条件

データソースの検証（重要）：

• Config Service API が呼び出されている（https://admin.hlx.page/config/{ORG}/sites.json）
• サイト一覧の取得元が API の応答であり、fstab.yaml やコードベースの分析ではない
• DA／ブロックライブラリの URL が Config Service のコンテンツソースから導出されており、code.owner/repo から推測されていない

コンテンツの検証：

• すべてのプロジェクト URL を含むクイックリファレンス表
• すべてのブロックが表形式で文書化されている
• すべてのテンプレートが必須メタデータとともに文書化されている
• 設定シートが文書化されている
• 公開ワークフローが説明されている
• よくある作業が文書化されている
• セクション／ページのメタデータオプションが一覧に記載されている
• トラブルシューティングが含まれている

出力の検証：

• PDF が正常に生成されている
• すべてのソースファイルが削除されている（PDF のみが残っている）

---

分かりやすい文書を作成するためのヒント

1. 表を使って、簡潔に参照できる情報をまとめます
2. 平易な言葉を使い、専門用語を避けます
3. 実際のプロジェクトコンテンツを使った例を示します
4. 文書化する前に手順をテストします