ppt

PPT スキル — デッキレベルのオーケストレーション

ファイルシステムをデータベースとして扱い、スライドデッキ（PPT／PowerPoint／プレゼンテーション）を作成します。各デッキは .pptwork/<deck-name>/ の下にあるフォルダーで、機械可読な deck.json、スライドごとの design.md と slide.html、および任意のアウトライン／調査メモで構成されます。

このスキルには、次のものが含まれます。

• 意図の明確化、ストーリー展開の計画、ビジュアル QC、エクスポートの方法論（このファイルと references/）。
• デッキの CRUD（deck.mjs）、ヘッドレスサムネイル生成（screenshot.mjs）、PPTX エクスポート（export.mjs。編集可能モードとラスター形式モードの両方）を行う scripts/ 配下のスクリプト。
• 1 ページ単位の作成を担当する、付属の ppt-html-authoring スキル（slide.html を実際に作成する際は、その SKILL.md をお読みください）。

このスキルには、assets/ 配下に 2 つの組み込みスターターバケットが含まれています。

• assets/corporate-light/ — 5 つのレイアウト（表紙、アジェンダ、2 カラム＋チャート、KPI 行、締めくくり）
• assets/claude-warm/ — 5 つのレイアウト（表紙、セクション、タイムライン、引用、ベントーグリッド）

各バケットには、すべてのレイアウトの id、pageType、description、authoringHints、htmlPath を記載した index.json があります。ストーリーの計画では index.json を参照してレイアウトを選び、作成時には該当する HTML を読み込んで構成の参考にします。スターターと並べて独自のバケットを追加することも、バケットを使わずに一から構成することもできます。

セットアップ（初回）

cd skills/ppt
npm install   # or `bun install`

スクリーンショット／エクスポートスクリプトは、実際のヘッドレスブラウザーを起動します。Chrome／Edge は次の順序で検索されます。PPT_BROWSER_EXECUTABLE 環境変数 → Playwright に同梱された Chromium → システムの Chrome（チャネル）→ システムの Edge。どれも利用できない場合は、npx playwright install chromium を一度実行してください。

エクスポートのツールチェーン：

ライブラリ	役割
playwright-core	slide.html のヘッドレス Chromium／Edge レンダリング、スクリーンショット
html2pptx-pro	編集可能な PPTX（HTML 構造のマッピング）— デフォルトのエクスポートエンジン
dom-to-pptx	DOM → スライド要素 — 診断用のバックアップ編集可能エンジン
pptxgenjs	PPTX ファイルの書き出し、ラスター形式でのエクスポート

作業ディレクトリ

すべてのスクリプトは process.cwd()/.pptwork/ を対象に動作します。ユーザーのプロジェクトルートから実行してください。

ディスク構成

全仕様については references/disk-layout.md をご覧ください。要点として、スライド順の唯一の信頼できる情報源は .pptwork/<deck>/deck.json です。各スライドのフォルダーには design.md、slide.html、thumbnail.png が格納されます。

エンドツーエンドのワークフロー

各フェーズを実行するのは 1 人のオペレーター（あなた）です。隠れたサブエージェントはありません。フェーズに入る際は、対応する references/<phase>.md をお読みください。

1. Clarify intent
2. (optional) Material digest        → references/material-digest.md
3. (optional) Research               → references/research.md
4. Story planning                    → references/story-planning.md
5. Initialize deck + first slides    → scripts/deck.mjs init / init-slide
6. Author each slide                 → ppt-html-authoring skill
7. Visual QC each slide              → references/visual-qc.md + scripts/screenshot.mjs
8. Export                            → scripts/export.mjs (+ references/export-troubleshooting.md)

ステップ 1 — 意図を明確にする

不足している情報だけを質問してください。作り上げないでください。

• 対象者（社内レポート／顧客向け提案／一般向け講演／研修）
• シナリオと長さ（会議時間、目標とする意思決定、オフラインでの閲覧の有無）
• ページ数の目安（下限／上限）
• スタイル／ブランド（企業テンプレート？ 参考にする特定の PPTX？ カラーパレット？）
• 必須セクション（ユーザーが指定しているもの）
• 出力言語
• 外部情報の検証が必要かどうか（数値／ニュース／市場データ）
• エクスポート形式：ユーザーが raster または editable のどちらを希望するか確認します
  • デフォルトでは raster を推奨します。ピクセル単位で忠実ですが、PowerPoint では編集できません
  • editable は PowerPoint 内での編集専用で、レイアウトがずれるリスクがあります。作成時は references/editable-html-rules.md に従う必要があります

ステップ 2 — 素材の要約（必要な場合）

次のいずれかに該当する場合に実施します。

• ユーザーが長い文書、複数のファイル、会議の議事録を提供した場合。
• 取り込んだ参考デッキの規模が大きい場合（HTML のページ数が多い）。

ユーザーが 1 行のトピックだけを提示した場合、またはすでに要約がある場合は省略します。

手順 → references/material-digest.md。

ステップ 3 — 調査（必要な場合）

次の場合に実施します。

• 市場規模、リリース頻度、ポリシーなど、時間とともに変化するデータがテーマに含まれる場合。
• ユーザーから数値や事実の検証を明示的に求められた場合。
• 競合他社や業界ベンチマークの情報が不足している場合。

このスキルには、独自のウェブ取得／検索ツールは含まれていません。ホストアプリに組み込まれている webfetch／websearch（OpenCode の webfetch／websearch、Claude Code の WebFetch／WebSearch、Cursor の WebSearch／WebFetch など）を使用します。構造化した調査結果を .pptwork/<deck>/materials/research.md に保存し、メインのコンテキストに混在しないようにします。

方法 → references/research.md。

ステップ 4 — ストーリーの計画

入力：明確化の結果 ＋（任意）ダイジェスト ＋（任意）調査の概要。
出力：5 ページ以上のデッキでは .pptwork/<deck>/outline.md、短いデッキでは構造化したコンテキスト内の要約。テンプレートの多様性、出典の引用、必須セクションの網羅性について、簡単にレビューします。

このフェーズでは slide.html を作成しないでください。

方法 → references/story-planning.md。

ステップ 5 — デッキとスライドの骨組みを初期化

node skills/ppt/scripts/deck.mjs init <deck-name> --mode raster
node skills/ppt/scripts/deck.mjs init-slide <deck-name> <slide-name>

<slide-name> は短く、内容が伝わる名前にします（intro-dark、agenda-clean、summary-bold）。

まず 1～2 ページを作成し、規模を広げる前にユーザーの確認を得てください。 構成上の誤りは時間以上のコストにつながります。12 ページ目でストーリー展開の誤りが見つかると、10 ページを作り直すことになります。

ステップ 6 — 各スライドを作成

1 ページ単位の作成は ppt-html-authoring スキルに委ねます。このスキルは独立したトリガーポイントなので、「スライドを 1 枚デザインしてほしい」だけのユーザーに、デッキ全体のパイプラインを実行する必要はありません。次のものを生成します。

• design.md（フロントマターの title と layout ＋ ## Content ／ ## Note ／ ## Design）
• slide.html（単一ファイルで完結。スピーカーノートは #ppt-speaker-notes-json のスクリプトアイランドにも反映）

デッキの exportMode を作成処理に渡します。exportMode=editable の場合は、作成ステップで references/editable-html-rules.md に従うよう指定します。

長いデッキでは、1 ページずつ作成します。すべてのページを 1 回の作成呼び出しにまとめないでください。

ステップ 7 — 各スライドのビジュアル QC

node skills/ppt/scripts/screenshot.mjs <deck> <slide>

次に、生成された thumbnail.png を読み込み、references/visual-qc.md のチェックリストに沿って確認します。チェックリストに合格するまで slide.html を少しずつ修正します。反復は最大 3 回とし、解決していない問題はユーザーに伝えます。

ステップ 8 — エクスポート

# default: editable via html2pptx-pro — editable, but still verify output
node skills/ppt/scripts/export.mjs <deck-name>

# high-fidelity fallback: raster — pixel-faithful, text not editable
node skills/ppt/scripts/export.mjs <deck-name> --mode raster

# backup editable engine for one-slide diagnostics
node skills/ppt/scripts/export.mjs <deck-name> --editable-engine dom-to-pptx

出力先の既定値は .pptwork/<deck-name>/<deck-name>.pptx です。--output <path> で変更できます。

デッキの deck.json に exportMode がある場合、--mode を省略すると、その設定に従います。exportMode のないデッキは editable として扱います。

編集可能（既定） モードでは、html2pptx-pro を使ってスライドの HTML を編集可能な PowerPoint オブジェクトに変換します。これが現在の主な方法ですが、PowerPoint での検証が必要です。フォント、複雑な CSS、レイアウトの特殊なケースでは、ずれが生じることがあります。

修正の手順は次のとおりです。

edit slide.html  →  screenshot.mjs to verify  →  export.mjs to ship

これが「デッキを編集する」ための推奨方法です。HTML を変更して再エクスポートしてください。.pptx の出力を編集しても、その変更が往復変換で維持されるとは限らないため、避けてください。

ラスター モードでは、各スライドを 1 枚の全ページ PNG に変換し、13.333×7.5 インチのスライドに配置します。編集可能な出力にずれが生じ、PowerPoint での編集可能性より見た目の忠実さを優先する場合に使用します。

dom-to-pptx は、診断用のバックアップ編集エンジンに限られます。実際のデッキでレイアウトのずれが確認されており、現在、バックアップとしてのエクスポートは 1 枚のスライドのみ対応しています。

エクスポート結果に問題がある場合は、references/export-troubleshooting.md を参照してください。

ユーザーが最初にラスター形式または複雑な HTML のデッキを作成し、後から編集可能な PPTX を求めた場合は、単に --mode editable を再実行しないでください。まず references/editable-html-rules.md に従って、各 slide.html を言語モデルで書き直します。その後、スクリーンショットで QC を行い、編集可能な形式でエクスポートします。

テンプレートバケット

組み込みのスターター：assets/corporate-light/ と assets/claude-warm/ （両方を使用したデッキについては、リポジトリの examples/ を参照してください）。ライブラリを拡張するには、assets/<bucket-name>/ の下にバケットを追加します。

バケットは、次の構成のディレクトリです。

assets/<bucket>/
├── index.json                     # array of template descriptors
├── html/<id>.html                 # one self-contained reference slide per id
├── specs/<id>.json                # optional structured zone description
└── materials/<id>/                # optional images/svgs the template uses
    └── manifest.json

index.json の最小エントリー（任意と記されていない項目はすべて必須です）：

{
  "id": "cover-hero",
  "pageType": "cover",
  "description": "Hero opener with full-bleed background and a single conclusion title.",
  "authoringHints": "Title goes in the centered `[data-role=hero-title]` slot. Background image at `[data-role=hero-bg]`.",
  "htmlPath": "html/cover-hero.html",
  "materialDir": "materials/cover-hero",
  "zones": [
    { "selector": "[data-role=hero-title]", "kind": "text" },
    { "selector": "[data-role=hero-bg]",    "kind": "image" }
  ]
}

ストーリーの計画で参照されるのは id / pageType / description / authoringHints のみです — 生の HTML は参照されません。HTML 本文は、作成フェーズで構成（バージョンのセーフエリア、列、階層、スロットの位置）を参考にするためのものです。参照用 HTML にあるプレースホルダーの文言（「Acme Corp」、「2024 Q3 revenue」、「scene illustration」）を実際のデッキにコピーしないでください。

テンプレートバケットがまだなくても、スキルは機能します。ストーリーの計画ではレイアウトを平易な言葉で説明でき、作成フェーズでは slide.html を一から作成できます。バケットを用意すると、作成ステップで実績のある構成を参考にできるため、両方のフェーズを短縮できます。

スクリプトリファレンス

スクリプト	目的
scripts/deck.mjs init <deck>	.pptwork/<deck>/deck.json のひな形を作成します。
scripts/deck.mjs init-slide <deck> <slide> [--at N]	スライドのフォルダーと空の design.md を作成し、deck.json に登録します。
scripts/deck.mjs move <deck> <slide> <to-pos>	スライドの順序を変更します。
scripts/deck.mjs delete <deck> <slide> [<slide>...]	スライドのフォルダーと deck.json のエントリーを削除します。
scripts/deck.mjs path <deck> <slide>	絶対パスとフォルダーの内容を表示します。
scripts/deck.mjs list <deck>	deck.json の順序でスライドを一覧表示します。
scripts/screenshot.mjs <deck> <slide>	ヘッドレスで slide.html をレンダリングし、thumbnail.png に出力します。
scripts/screenshot.mjs <slide-dir>	スライドディレクトリを直接指定した場合も同様です。
scripts/export.mjs <deck> [--mode editable|raster] [--output ...]	デッキを単一の .pptx にエクスポートします。

各スクリプトは stdout に [Done] / [State] / [Next] / [Hint] / [Error] ブロックを出力します。これらのタグを使って次のステップを把握してください。ToDo リストとして扱います。

よくある落とし穴

• 確認を省略してストーリーの計画に進む → ユーザーから「これは望んでいたものではありません」と言われます。
• ユーザーが資料を詰め込んだ 10MB の PPTX を渡したのに、最初に資料のダイジェストを実行しなかった → コンテキストがあふれます。
• 時事的なページを事前調査なしで作成する → 数値を幻覚します。
• 長いデッキでビジュアルの品質確認をしない → エクスポートしたファイルで 3 ページが切れています。
• 20 ページ分の作成を一度にまとめて実行する → 最初の数ページで作成が止まります。「1 ページのみ」は厳守すべき契約です。
• ユーザーから頼まれていないのに --mode editable を選択する → 避けてください。既定はラスターモードです。複雑な CSS / フォント / SVG では編集可能なエクスポートが崩れるため、ユーザーが PowerPoint 内での編集を明示的に必要としている場合のみ編集可能モードを使用します。
• ラスターデッキを作成した後にユーザーが編集可能な形式を求めたのに、編集可能形式のルールに合わせて HTML を書き直さずに直接エクスポートする → 誤りです。
• 編集可能なエクスポートの表示が崩れる → --mode editable フラグを外してください。既定のラスターモードが最も確実な方法です。同じスライドを調整し続けるために編集可能モードにとどまらないでください。
• ユーザーが「スライドを編集して」と頼んだときに、エクスポート済みの .pptx を変更しようとする → 不適切な手順です。代わりに slide.html を編集し、再度スクリーンショットを撮影してからエクスポートします。HTML が正本です。
• web_fetch / web_search という名前のツールを使おうとして存在しなかった → ホストに組み込まれている webfetch / websearch を使用してください。このスキルにはツールが含まれていません。