ln-150-presentation-creator

パス： ファイルパス（shared/、references/、../ln-*）は、skills リポジトリのルートを基準とします。CWD に見つからない場合は、この SKILL.md ディレクトリを特定し、1 つ上の階層をリポジトリのルートとして使用してください。shared/ がない場合は、https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path} から WebFetch を使ってファイルを取得してください。

HTML プレゼンテーションビルダー

このスキルは、既存のプロジェクトドキュメントから、インタラクティブで自己完結型の HTML プレゼンテーションを作成します。Markdown ドキュメントを、図、折りたたみ可能なセクション、最新の UI を備えた、プロフェッショナルでナビゲーションしやすい Web プレゼンテーションに変換します。

目的

既存の Markdown ドキュメントを、6 つのタブ（概要、要件、アーキテクチャ／C4、技術仕様、ロードマップ、ガイド）と Mermaid の図に対応した、インタラクティブで自己完結型の HTML プレゼンテーションに変換します。

このスキルを使用する場面

このスキルは L2 ワーカーであり、ln-100-documents-pipeline オーケストレーターから呼び出されるか、単独で使用されます。

次の場合にこのスキルを使用します：

• 既存のドキュメントから HTML プレゼンテーションを作成する
• ドキュメント更新後にプレゼンテーションを再作成する
• 共有用の単独プレゼンテーションを作成する（ドキュメント一式のセットアップは不要）
• 元ドキュメントがプレゼンテーション生成に適した状態か検証する

ワークフローの一部： ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator（任意）→ ln-150-presentation-creator

前提条件： docs/ ディレクトリに、次の必須ファイルを含む既存のドキュメントがあること：

• docs/project/requirements.md（必須）
• docs/project/architecture.md（必須）
• docs/project/tech_stack.md（必須）

任意のファイル（プレゼンテーションを充実させますが、必須ではありません）：

• docs/project/api_spec.md、database_schema.md、design_guidelines.md、infrastructure.md、runbook.md
• docs/reference/adrs/*.md（Category: Strategic|Technical の ADR）
• docs/reference/guides/*.md（手順ガイド）
• docs/tasks/kanban_board.md（ロードマップ用のエピックストーリーカウンター）

ワークフロー

このスキルは、7 フェーズのワークフローに従います：ドキュメントを読み込む → 元ファイルの存在を検証する → 元ファイルの品質を検証する → ディレクトリを作成する → テンプレートをコピーする → コンテンツを挿入する → HTML を構築する。

フェーズ 1：ドキュメントを読み込む - docs/ からすべてのプロジェクトドキュメントを読み込みます
フェーズ 2：元ファイルの存在を検証する - 必須ファイル（requirements.md、architecture.md、tech_stack.md）の存在を確認し、任意ファイルがない場合は警告します
フェーズ 3：元ファイルの品質を検証する - 図、プレースホルダー、コンテンツの長さを確認します（読み取り専用の検証）
フェーズ 4：ディレクトリを作成する - presentation/ ディレクトリと、ナビゲーションハブとなる README.md を作成します
フェーズ 5：テンプレートをコピーする - HTML/CSS/JS テンプレートを assets/ にコピーします
フェーズ 6：コンテンツを挿入する - MD ドキュメントを解析し、タブファイル内のプレースホルダーを置換して、サンプルブロックを削除します
フェーズ 7：HTML を構築する - モジュールコンポーネントを組み立てて、単独で動作する presentation_final.html を作成します

必ず確認： 各フェーズの詳細なワークフローについては、references/phases_detailed.md を読み込んでください。

---

Phase 1: ドキュメントを読み込む

目的：変換対象となるプロジェクトのドキュメントをすべて読み込みます。

実行タイミング：常に実行します（最初のフェーズ）

手順：

1. ソースとして docs/ を使用する：

   • docs/project/、docs/reference/、docs/tasks/ ディレクトリからドキュメントを読み込みます
   • ln-114、ln-112、ln-113 によって作成される標準の配置場所です

2. 主要な MD ドキュメントを読む：

   • project/requirements.md - 機能要件
   • project/architecture.md - アーキテクチャ設計、C4 図
   • project/tech_stack.md - 技術バージョン、Docker 設定
   • project/api_spec.md - API エンドポイント、認証（存在する場合）
   • project/database_schema.md - データベーススキーマ、ER 図（存在する場合）
   • project/design_guidelines.md - UI/UX デザインシステム（存在する場合）
   • project/infrastructure.md - インフラストラクチャの一覧（存在する場合）
   • project/runbook.md - 運用手順（存在する場合）

3. ADR を読む（存在する場合）：

   • reference/adrs/adr-001-*.md から adr-NNN-*.md まで
   • ADR のメタデータ（ステータス、日付、タイトル、Category: Strategic|Technical）を解析します

4. ガイドを読む（存在する場合）：

   • reference/guides/*.md - Guides タブ用の手順ガイド

5. カンバンボードを読む（存在する場合）：

   • tasks/kanban_board.md - Roadmap の進捗状況を把握するための Epic Story Counters テーブル

6. メタデータを抽出する：

   • ドキュメントからプロジェクト名、日付、バージョンを取得します
   • Mermaid の図のブロックを保持します

出力：検証と HTML 生成に使用できる状態のドキュメントデータ

---

Phase 2: ソースドキュメントの存在を検証する

目的：プレゼンテーションの構築前に、必要なソースドキュメントが存在することを確認します。不完全なプレゼンテーションの構築を防ぎます。

実行タイミング：Phase 1 の後（ドキュメントの読み込み後）

手順：

2.1 必須ファイルを確認する

必須（存在する必要があります。見つからない場合は実行を中止します）：

• ✅ docs/project/requirements.md
• ✅ docs/project/architecture.md
• ✅ docs/project/tech_stack.md

必須ファイルごとに、次の手順を実行します。

1. Glob ツールを使用します：pattern: "docs/project/{filename}"
2. 見つからない場合：
   • 不足ファイルのリストに追加します
3. 見つかった場合：
   • ファイルサイズが 100 バイトを超えていることを確認します（空でないこと）

必須ファイルが 1 つでも見つからない、または空の場合：

❌ ERROR: Cannot build presentation - missing required documentation:
  - docs/project/requirements.md [missing/empty]
  - docs/project/architecture.md [missing/empty]

Suggestion: Run ln-111-project-docs-creator to create missing files.

STOP execution.

2.2 任意ファイルを確認する

任意（プレゼンテーションを充実させます。不足している場合は警告しますが、処理を続行します）：

• ⚠️ docs/project/api_spec.md（バックエンドプロジェクト向け）
• ⚠️ docs/project/database_schema.md（データベースを使用するプロジェクト向け）
• ⚠️ docs/project/design_guidelines.md（フロントエンドプロジェクト向け）
• ⚠️ docs/project/runbook.md（運用プロジェクト向け）

任意ファイルごとに、次の手順を実行します。

1. Glob ツールを使用します：pattern: "docs/project/{filename}"
2. 見つからない場合：
   • 不足している任意ファイルのリストに追加します

任意ファイルが不足している場合：

⚠ WARN: Optional files missing: [list]
Presentation will have reduced content in some tabs.
Continue execution.

2.3 任意ディレクトリを確認する

任意のディレクトリ：

• docs/reference/adrs/ - ADR ファイル（adrs/*.md）が存在するか確認します
• docs/reference/guides/ - ガイドファイル（guides/*.md）が存在するか確認します
• docs/tasks/kanban_board.md - Roadmap のデータがあるか確認します

ディレクトリごとに、次の手順を実行します。

1. Glob ツールを使用してファイルを検索します
2. 空または存在しない場合：
   • ログに記録します：ℹ Optional directory empty: {directory} - related tab will show placeholder

2.4 検証結果の概要を報告する

概要をログに記録します。

✓ Source documentation validation completed:
  Required files:
    - ✅ requirements.md (found, 8.5 KB)
    - ✅ architecture.md (found, 15.2 KB)
    - ✅ tech_stack.md (found, 3.1 KB)
  Optional files:
    - ⚠️ api_spec.md (missing - Technical Spec tab will have reduced content)
    - ✅ database_schema.md (found, 4.7 KB)
    - ⚠️ design_guidelines.md (missing)
  Optional directories:
    - ✅ adrs/ (5 ADR files found)
    - ⚠️ guides/ (empty - Guides tab will show placeholder)
    - ✅ kanban_board.md (found - Roadmap will show progress)

出力：検証成功（すべての必須ファイルが存在する）またはエラー（実行を中止）

---

フェーズ 3：ソースコンテンツの品質を検証する

目的：ソースドキュメントに十分なコンテンツが含まれていることを確認します。コンテンツが不完全な場合は警告しますが、実行はブロックしません。

実行タイミング：フェーズ 2 の後（ソースファイルが存在する）

実施するチェック（警告のみ、ブロックなし）：

1. Mermaid 図：architecture.md に図が 1 つ以上、database_schema.md に ER 図が必要です
2. プレースホルダー：{{PLACEHOLDER}}、[Add your ...]、TODO: のパターンを検出します
3. コンテンツの長さ：requirements.md は 500 語超、architecture.md は 1000 語超、tech_stack.md は 200 語超であること

自動修正：ありません。ln-115 は読み取り専用です。問題を修正するには ln-111-project-docs-creator を実行してください。

出力：警告を含むコンテンツ品質レポート

📖 詳細なワークフロー：phases_detailed.md の §Phase 3 を参照

---

フェーズ 4：プレゼンテーションディレクトリと README を作成する

目的：プレゼンテーションのディレクトリ構造とナビゲーションハブをセットアップします。

実行タイミング：フェーズ 3 の後（ソースの検証が完了し、警告が記録されている）

手順：

1. プレゼンテーションディレクトリを作成する：

   mkdir -p docs/presentation/
   

2. presentation/README.md が存在するか確認する：

   • Glob ツールを使用：pattern: "docs/presentation/README.md"
   • ファイルが存在する場合：
     • 作成をスキップします
     • ログに記録：✓ docs/presentation/README.md already exists (preserved)
     • フェーズ 5 に進みます
   • 存在しない場合：
     • 手順 3 に進みます

3. テンプレートから presentation/README.md を作成する：

   • テンプレートをコピー：references/presentation_readme_template.md → docs/presentation/README.md
   • プレースホルダーを置き換えます：
     • {{PROJECT_NAME}} — requirements.md から取得
     • {{LAST_UPDATED}} — 現在の日付（YYYY-MM-DD）
   • コンテンツの構成：
     • 目的：このプレゼンテーションについて
     • クイックナビゲーション：presentation_final.html と assets/ へのリンク
     • カスタマイズガイド：assets/ 内のソースファイルの編集方法
     • ビルド手順：変更後の再ビルド方法
     • メンテナンス：再ビルドのタイミング、検証チェックリスト

4. ユーザーに通知する：

   • 作成した場合：✓ Created docs/presentation/README.md (navigation hub)
   • スキップした場合：✓ docs/presentation/README.md already exists (preserved)

出力：docs/presentation/README.md（作成済み、または既存）

---

フェーズ 5：テンプレートをプロジェクトにコピーする

目的：スキルの references/ から HTML/CSS/JS テンプレートをプレゼンテーションディレクトリにコピーします。

実行タイミング：フェーズ 4 の後（プレゼンテーションディレクトリが存在する）

手順：

1. assets が存在するか確認する：

   • Glob ツールを使用：pattern: "docs/presentation/assets/"
   • docs/presentation/assets/ が存在する場合：
     • コピーをスキップします（ユーザーがファイルをカスタマイズしている可能性があります）
     • ログに記録：✓ Presentation assets already exist - preserving user customizations
     • フェーズ 6 に進みます
   • 存在しない場合：
     • 手順 2 に進みます

2. テンプレートファイルをコピーする：

   cp references/presentation_template.html → docs/presentation/assets/
   cp references/styles.css → docs/presentation/assets/
   cp references/scripts.js → docs/presentation/assets/
   cp references/build-presentation.js → docs/presentation/assets/
   cp -r references/tabs/ → docs/presentation/assets/tabs/
   

3. コピーした構成を確認する：

   docs/presentation/assets/
   ├── presentation_template.html   # Base HTML5 + 6 tab navigation
   ├── styles.css                    # ~400-500 lines
   ├── scripts.js                    # Tab switching + Mermaid init
   ├── build-presentation.js         # Node.js build script
   └── tabs/
       ├── tab_overview.html         # Landing page
       ├── tab_requirements.html     # FRs + ADRs
       ├── tab_architecture.html     # C4 diagrams
       ├── tab_technical_spec.html   # API + Data + Deployment
       ├── tab_roadmap.html          # Epic list
       └── tab_guides.html           # How-to guides
   

出力：テンプレートファイルが docs/presentation/assets/ にコピーされます（既に存在する場合はスキップ）

注：テンプレートにはプレースホルダー（{{VARIABLE_NAME}}）が含まれており、フェーズ 6 で置き換えられます。

---

フェーズ 6：コンテンツの挿入とサンプルのクリーンアップ

目的：MD ドキュメントを解析し、HTML テンプレートに挿入して、サンプルブロックを削除します。

実行タイミング：フェーズ 5 の後（assets/ にテンプレートが存在する）

手順：

1. MD ドキュメントを解析する（10 のソース）：requirements、architecture、tech_stack、api_spec、database_schema、design_guidelines、runbook、adrs/.md、kanban_board、guides/.md
2. コンテンツを挿入する：解析したコンテンツで、6 つのタブファイル内の {{PLACEHOLDER}} を置き換えます
3. サンプルを削除する：すべてのタブから ... ブロックを削除します

タブのプレースホルダー：概要（5）、要件（4 + NFR 禁止）、アーキテクチャ（5）、技術仕様（4）、ロードマップ（3）、ガイド（6）

検証：サンプルマーカーがないこと、ハードコードされた e コマースデータがないこと、プロジェクト固有のコンテンツのみであること

出力：ビルドに使用できる、クリーンなプロジェクト固有のタブファイル

📖 プレースホルダーの参照とサンプルの変換：phases_detailed.md の §Phase 6 を参照

---

フェーズ 7：最終プレゼンテーションのビルド

目的：モジュール化されたコンポーネントを組み合わせ、スタンドアロンの HTML ファイルを作成します。

実行タイミング：フェーズ 6 の後（コンテンツを挿入し、例を削除した後）

手順：

1. presentation_final.html が存在するか確認する（自動化のための自動再ビルド）：

   • Glob ツールを使用：pattern: "docs/presentation/presentation_final.html"
   • ファイルが存在する場合：
     • ✓ 自動再ビルド（生成ファイルのため、安全な操作です）
     • ログ：ℹ Rebuilding presentation_final.html (generated file, safe to rebuild)
     • ステップ 2 に進みます
   • 存在しない場合：
     • ログ：Creating presentation_final.html
     • ステップ 2 に進みます

   自動再ビルドする理由：

   • presentation_final.html は生成ファイルです（信頼できる情報源：assets/ ディレクトリ）
   • 再ビルドしても安全です。データが失われることはありません（ソースファイルは assets/ に保持されます）
   • ln-110-documents-pipeline から呼び出された場合も、完全自動のワークフローを維持できます
   • assets/ 内のユーザーによるカスタマイズは保持されます（最終 HTML のみが再生成されます）

2. プレゼンテーションのアセットディレクトリに移動する：

   cd docs/presentation/assets/
   

3. ビルドスクリプトを実行する：

   node build-presentation.js
   

4. ビルドスクリプトの処理：

   • ステップ 1：presentation_template.html を読み込みます
   • ステップ 2：styles.css を読み込み、<style> タグにインライン化します
   • ステップ 3：scripts.js を読み込み、<script> タグにインライン化します
   • ステップ 4：6 つのタブファイルをすべて読み込み、空の <div> コンテナーに挿入します
   • ステップ 5：{{PLACEHOLDERS}} を実際の値に置き換えます
   • ステップ 6：../presentation_final.html に書き込みます

5. 出力を検証する（ファイルがビルドされた場合のみ）：

   • ファイルサイズを確認します（約 120～150 KB が目安です）
   • Mermaid 図の構文が有効であることを確認します
   • ログ：✓ Build completed successfully

6. ユーザーに通知する：

   • 再ビルドした場合（ファイルが存在していた場合）：✓ Rebuilt docs/presentation/presentation_final.html (~120-150 KB)
   • 作成した場合（ファイルが存在しなかった場合）：✓ Created docs/presentation/presentation_final.html (~120-150 KB)
   • 次の内容を案内します：ブラウザーでテストするには、ダブルクリックして開くか、http-server を使用してください

出力：docs/presentation/presentation_final.html（自己完結型、約 120～150 KB、外部依存関係は Mermaid.js CDN のみ）

⚠️ 重要な注意：

presentation_final.html は、assets/ 内のモジュール化されたソースファイルからビルドされる生成ファイルです。

• ❌ presentation_final.html を直接編集しないでください — 次回の再ビルドで変更が失われます
• ✅ assets/ ディレクトリ内のソースファイル（テンプレート、タブ、スタイル、スクリプト）を編集してください
• 🔄 変更後に再ビルドしてください：cd assets/ && node build-presentation.js

---

完全な出力構成

docs/
├── project/                      # Source documentation (input)
│   ├── requirements.md
│   ├── architecture.md
│   ├── tech_stack.md
│   ├── api_spec.md (conditional)
│   ├── database_schema.md (conditional)
│   ├── design_guidelines.md (conditional)
│   └── runbook.md (conditional)
├── reference/                    # Source documentation (input)
│   ├── adrs/
│   │   └── *.md (Category: Strategic | Technical)
│   └── guides/
│       └── *.md (optional)
├── tasks/                        # Source documentation (input)
│   └── kanban_board.md (Epic Story Counters)
└── presentation/                 # Output directory
    ├── README.md                 # Navigation hub
    ├── presentation_final.html   # Final standalone HTML (~120-150 KB)
    └── assets/                   # Modular HTML structure
        ├── presentation_template.html  # Base HTML5 + 6 tabs
        ├── styles.css                  # ~400-500 lines
        ├── scripts.js                  # Tab switching + Mermaid
        ├── build-presentation.js       # Node.js build script
        └── tabs/
            ├── tab_overview.html       # Landing page
            ├── tab_requirements.html   # FRs + ADRs
            ├── tab_architecture.html   # C4 diagrams
            ├── tab_technical_spec.html # API + Data + Deployment
            ├── tab_roadmap.html        # Epic list
            └── tab_guides.html         # How-to guides

注：プレゼンテーションは docs/project/、docs/reference/、docs/tasks/ から読み込みますが、docs/presentation/ に出力します。

---

HTML の機能

• 信頼できる唯一の情報源：情報を重複させず、それぞれの情報を必ず 1 つのタブのみに配置します
• ランディングページ（概要）：課題／解決策／ビジネス価値、ステークホルダー、ドキュメントガイド、クイックファクト、技術スタックのバッジ
• インタラクティブなナビゲーション：SCOPE タグ付きの 6 つのタブ、状態の保持（localStorage）、スムーズな画面遷移
• テーブルベースのレイアウト：FR のテーブルのみ（非機能要件は禁止）、アーキテクチャの概要テーブル
• 簡略化されたロードマップ：対象範囲内／対象範囲外のセクション、ステータスバッジ、依存関係／成功基準を含む、縦型のエピック一覧
• ADR の整理：カテゴリ（戦略／技術）ごとにグループ化し、アコーディオンで表示。コンテンツ全体をインラインで掲載
• 図の表示：タブ切り替え時に再レンダリングする Mermaid.js（C4、ER、シーケンス、デプロイメント）
• レスポンシブデザイン：モバイルファースト（ブレークポイントは 320px／768px／1024px 以上）
• 折りたたみ可能なセクション：スクロール位置を保持して自動で折りたたみ
• モダンな UI：すっきりとしたプロフェッショナルなデザイン、WCAG 2.1 レベル AA 準拠
• 英語：プレゼンテーションのコンテンツはすべて英語です

---

ベストプラクティス

冪等な操作：README.md と assets/ を保持し（ユーザーによるカスタマイズを維持）、presentation_final.html を自動的に再ビルドします。

フェーズごとの主なルール：

• Phase 2：必須ファイルがない場合は停止します。Phase 3：警告のみ（処理は続行）
• Phase 5：既存の assets/ を上書きしません（ユーザーによるカスタマイズを維持）
• Phase 6：すべてのサンプルブロックを削除し、XSS をエスケープし、有効な Mermaid 構文を使用します
• Phase 7：出力が 200 KB を超える場合は警告します

---

カスタマイズオプション

assets/styles.css（テーマ設定用の CSS 変数）、assets/presentation_template.html（レイアウト／タブ）、または assets/tabs/*.html（タブのコンテンツ）を編集します。

⚠️ カスタマイズ後は必ずプレゼンテーションを再ビルドしてください：

cd assets/
node build-presentation.js

重要： presentation_final.html を直接編集しないでください。ビルドのたびに上書きされる生成ファイルです。

---

前提条件

オーケストレーター：ln-110-documents-pipeline | 単独実行：可（既存ドキュメントの再ビルド／検証）

必須ファイル：requirements.md、architecture.md、tech_stack.md（docs/project/ 内） 任意のファイル：api_spec、database_schema、design_guidelines、runbook、adrs/.md、guides/.md、kanban_board.md

依存関係：Node.js v18 以降、モダンブラウザー、インターネット接続（Mermaid CDN）

---

完了の定義

• docs/project/、docs/reference/、docs/tasks/ からすべてのドキュメントを読み込み、メタデータを抽出し、Mermaid ブロックを保持している
• 必須ファイル（requirements.md、architecture.md、tech_stack.md）が存在する。不足している場合はエラー
• 図を確認し、プレースホルダーを検出し、コンテンツの長さを確認している（警告のみ）
• docs/presentation/ と README.md を作成している
• すべてのテンプレートを含む assets/ を作成している。または、既存の場合は保持している
• 6 つのタブすべてにコンテンツが入力され、サンプルブロックが削除され、`` マーカーがなく、ハードコードされたデータがない
• node build-presentation.js を実行し、presentation_final.html を作成し、ブラウザーでテストしている

出力： docs/presentation/presentation_final.html + assets/ + README.md

---

重要なルール

• 必須ファイルは 3 つ： requirements.md、architecture.md、tech_stack.md が存在する必要があります。不足している場合は実行を停止します
• assets/ を上書きしない： 既存の assets/ ディレクトリは保持されます（ユーザーによるカスタマイズを維持）。再生成するのは presentation_final.html のみです
• すべてのサンプルブロックを削除する： すべての ... を削除してください。出力にハードコードされた E コマースのデータを含めないでください
• presentation_final.html を直接編集しない： 生成ファイルです。assets/ 内のソースファイルを編集して再ビルドしてください
• Node.js v18 以降が必要： ビルドスクリプトは最終 HTML の組み立てに Node.js を使用します

---

参照ファイル

• フェーズの詳細なワークフロー： references/phases_detailed.md
• プレゼンテーションの README テンプレート： references/presentation_readme_template.md
• HTML テンプレート： references/presentation_template.html
• スタイル： references/styles.css
• スクリプト： references/scripts.js
• ビルドスクリプト： references/build-presentation.js
• タブのテンプレート： references/tabs/tab_overview.html、tab_requirements.html、tab_architecture.html、tab_technical_spec.html、tab_roadmap.html、tab_guides.html

---

トラブルシューティング

• エラー：必須ファイルがありません：ln-111-project-docs-creator を実行して requirements.md、architecture.md、tech_stack.md を作成します
• 警告：図がありません：architecture.md に Mermaid 図（C4 のコンテキスト／コンテナー／コンポーネント）を、database_schema.md に ER 図を追加します
• 警告：プレースホルダーが見つかりました：ビルド前にソース MD ファイルのドキュメントを完成させます
• 警告：コンテンツが不足しています：ドキュメントを充実させます（requirements.md は 500 語超、architecture.md は 1000 語超、tech_stack.md は 200 語超）
• ビルドスクリプトが失敗する：Node.js v18 以降であることを確認し、assets/ に移動して、すべてのファイルが存在することを確認します
• Mermaid 図が表示されない：Mermaid Live Editor で構文を確認し、CDN が読み込まれていることを確認します
• タブが切り替わらない：JavaScript が読み込まれていることを確認し、ブラウザーのコンソールでエラーを確認します
• ファイルが大きすぎます（>200 KB）：図を減らし、CSS／JS を圧縮し、未使用のルールを削除します

---

バージョン： 8.0.0 最終更新日： 2025-12-12