paper-slide-deck

論文スライドデッキジェネレーター

学術論文やコンテンツを、図を自動抽出してプロ品質のスライドデッキ画像に変換します。

使用方法

/paper-slide-deck path/to/paper.pdf
/paper-slide-deck path/to/paper.pdf --style academic-paper
/paper-slide-deck path/to/content.md --style sketch-notes
/paper-slide-deck path/to/content.md --audience executives
/paper-slide-deck path/to/content.md --lang zh
/paper-slide-deck path/to/content.md --slides 10
/paper-slide-deck path/to/content.md --outline-only
/paper-slide-deck  # Then paste content

セットアップ（一度だけ）

TypeScript スクリプト（merge-to-*、detect-figures、extract-figure、 apply-template）の実行には Node の依存関係が必要です。一度インストールしてください。

cd ${SKILL_DIR}/scripts && npm install

これにより、canvas、pdfjs-dist、pptxgenjs、pdf-lib がインストールされます（package-lock.json でバージョンが固定されています）。スクリプトが missing Node dependency "<name>" で終了した場合は、 上記のコマンドを実行してください。Python ジェネレーター（generate-slides.py）は初回実行時に google-genai を自動インストールします。

PyMuPDF もインストールしてください（pip install pymupdf）。ビットマップを埋め込んだページ（X 線画像、CAM ヒートマップ、写真）から図を抽出する際、extract-figure.ts の pdfjs + canvas 経由で失敗した場合に、確実な代替手段となります。 医用画像論文では例外ではなく一般的なケースのため、PyMuPDF は任意ではなく必須として扱ってください。

Pillow もインストールしてください（pip install Pillow）。Gemini が image/webp を返すと、すべてのスライドで Pillow による PNG 変換が行われます。インストールされていないと、「converting it needs Pillow (pip install Pillow)」というエラーが各画像で発生します。PyMuPDF と同様に必須として扱ってください。

画像生成と API キーがない場合の対応

画像生成には GOOGLE_API_KEY／GEMINI_API_KEY（Gemini API）または Gemini Web スキルのいずれかが必要です。API キーがなく、Web オプションも利用できない場合でも、スキルは機能を制限したモードで動作します。処理を中断しないでください。

1. --outline-only を指定して実行し、アウトラインとプロンプトを生成します（画像は生成しません）。
2. ソース PDF がある場合は、detect-figures.ts + extract-figure.ts + apply-template.ts を使って実際の図表を抽出します（API キー不要 — レンダリングのみ）。
3. 存在するスライド（extract で取得したページ）を PPTX／PDF にまとめ、キーを利用できるようになったときに後から画像を生成できるよう、prompts/ をユーザーに渡します。

スクリプトのディレクトリ

重要：すべてのスクリプトは、このスキルの scripts/ サブディレクトリにあります。

エージェントの実行手順：

1. この SKILL.md ファイルのディレクトリパスを SKILL_DIR として特定します
2. スクリプトのパス = ${SKILL_DIR}/scripts/<script-name>.ts
3. このドキュメント内のすべての ${SKILL_DIR} を実際のパスに置き換えます

スクリプト一覧：

スクリプト	用途
scripts/generate-slides.py	Gemini API を使って AI スライドを生成（Python）
scripts/merge-to-pptx.ts	スライドを PowerPoint に結合
scripts/merge-to-pdf.ts	スライドを PDF に結合
scripts/detect-figures.ts	PDF 内の図表を自動検出（ヒューリスティック。ページを確認してください）
scripts/extract-figure.ts	PDF のページ全体を PNG にレンダリング（任意の --crop に対応。PyMuPDF による代替処理あり）
scripts/apply-template.ts	図のコンテナテンプレートを適用

オプション

オプション	説明
--style <name>	ビジュアルスタイル — ギャラリーと自動選択ルールは references/style-selection.md を参照
--audience <type>	対象読者：初心者、中級者、専門家、エグゼクティブ、一般
--lang <code>	出力言語（en、zh、ja など）
--slides <number>	スライドの目標枚数
--outline-only	アウトラインのみを生成し、画像生成をスキップ

スタイルとレイアウトの選択：スタイルを選ぶ際（明示的に指定する場合も、コンテンツの特徴から自動選択する場合も）、references/style-selection.md を読んでください。そこには、文字化けした数式や数字に関する学術的シグナルの注意事項も記載されています。アウトラインの // LAYOUT ヒント（スライドごとの Layout: <name>）を作成する場合に限り、references/layout-gallery.md を読んでください。

デザインの理念

このデッキは、ライブプレゼンテーションではなく、閲覧と共有を目的に設計されています。

• 各スライドは、口頭での補足がなくても内容が理解できるようにします
• スクロールしながら論理的な流れで読めるよう、コンテンツを構成します
• 各スライドに必要な背景情報をすべて含めます
• ソーシャルメディアでの共有とオフラインでの閲覧に最適化します

ファイル管理

出力ディレクトリ

各セッションでは、コンテンツのスラッグを名前にした独立したディレクトリを作成します。

slide-deck/{topic-slug}/
├── source-{slug}.{ext}    # Source files (text, images; source-paper.pdf for papers)
├── figures.json           # Figure-detection results (academic PDFs)
├── outline.md             # Final outline (with IMAGE_SOURCE blocks)
├── outline-{style}.md     # Style variant outlines
├── extracted/             # Raw PDF page extractions (pre-template)
├── figures/               # Extracted figure crops (pre-template)
├── prompts/
│   └── {NN}-slide-{slug}.md, ...
├── {NN}-slide-{slug}.png  # Final slide images in the deck ROOT — both AI-generated
│                          #   and extracted-figure slides; ext may be .jpg
├── {topic-slug}.pptx
└── {topic-slug}.pdf

スラッグの生成：

1. コンテンツから主要なトピックを抽出します（2～4語、ケバブケース）
2. 例：「Introduction to Machine Learning」→ intro-machine-learning

競合の解決

slide-deck/{topic-slug}/ がすでに存在する場合：

• タイムスタンプを追加します：{topic-slug}-YYYYMMDD-HHMMSS
• 例：intro-ml が存在する場合 → intro-ml-20260118-143052

ソースファイル

すべてのソースを source-{slug}.{ext} という名前でコピーします：

• source-article.md（本文コンテンツ）
• source-diagram.png（会話からの画像）
• source-data.xlsx（追加ファイル）

テキスト、画像、会話からのファイルなど、複数のソースに対応しています。

ワークフロー

ステップ 1：コンテンツを分析する

1. ソースコンテンツを保存します（貼り付けられた場合は source.md として保存します）

2. 詳細なコンテンツ分析には references/analysis-framework.md を参照します

3. スタイルを決定します（--style を使用するか、手がかりから自動選択します）

4. 言語を検出します（ソースとユーザーの希望言語）

5. スライド数を計画します（--slides または動的に決定します）

6. 学術論文（図を含む PDF）の場合：図の自動検出を実行します：

   npx -y bun ${SKILL_DIR}/scripts/detect-figures.ts --pdf source-paper.pdf --output figures.json
   

   検出されたすべての図・表、そのページ番号、キャプションを含む JSON ファイルが出力されます。

   キャプションの検出はヒューリスティックに基づくため、特に最初のページのティーザーは確認してください。 行頭に基づく Figure N マッチャーは、独立した行にあるキャプション（1 段組レイアウト）を確実に検出しますが、最初のページが 2 段組で、図のキャプションが本文に挟まれている場合は検出できません。これは、論文で最も重要なアーキテクチャ図や概要図であることがよくあります。detect-figures の実行後は、ソース内の Figure 1 を必ず照合してください。論文本文で参照されている Figure N が figures.json にない場合は、// IMAGE_SOURCE ブロックを手動で追加し、PyMuPDF フォールバックを使用して抽出してください。figures.json が完全だとは限りません。

ステップ 2：アウトラインのバリエーションを生成する

1. ユーザーが --style <name> を明示的に渡した場合は、そのスタイルを直接使用し、以下のバリエーションに関する質問は省略します（明示的に選択した後で再度尋ねるのは無駄です）。それ以外の場合は、コンテンツ分析に基づいてスタイルのバリエーション案を 3 つ生成します
2. 構成には references/outline-template.md を参照します
3. 学術論文の場合は IMAGE_SOURCE を自動入力します：
   • ステップ 1 の figures.json を読み込みます
   • references/analysis-framework.md のセクション 8 のルールに従って、図をスライドに割り当てます
   • 適切なスライドに // IMAGE_SOURCE ブロックを自動的に追加します：
     • アーキテクチャ図・パイプライン図 → 手法のスライド（Source: extract）
     • 結果の表 → 定量的な結果のスライド（Source: extract）
     • 比較画像 → 定性的な結果のスライド（Source: extract）
     • 概念図・簡単な図 → AI による生成に任せます（Source: generate または省略）
4. バリエーションごとに outline-{style}.md として保存します

ステップ 3：ユーザーの確認

該当するすべての選択肢を含む AskUserQuestion を 1 回だけ行います：

質問	質問するタイミング
スタイルのバリエーション	--style が渡されていない場合のみ（3 つの選択肢とカスタム）。--style が明示されている場合は、それが回答です
言語	ソースの言語とユーザーの言語が異なる場合のみ

選択後：

• 選択された outline-{style}.md を outline.md にコピーします
• リクエストに応じて、別の言語で再生成します
• ユーザーは outline.md を編集して微調整できます

--outline-only が指定されている場合は、ここで終了します。

ステップ 4：プロンプトを生成する

1. references/base-prompt.md を読み込みます
2. アウトラインのスタイル指示と組み合わせます
3. スライド固有のコンテンツを追加します
4. アウトラインで Layout: が指定されている場合は、プロンプトにレイアウトの指示を含めます：
   • 画像の構成を決めるため、レイアウトの特徴を参照します
   • 例：Layout: hub-spoke → 「関連項目が中央のコンセプトから放射状に広がる構成」
5. prompts/ ディレクトリに保存します

ステップ 5：画像生成方法の選択

画像を生成する前に、生成方法をユーザーに選択してもらいます。

AskUserQuestion を使用し、次の選択肢を提示します。

オプション	ラベル	説明
1	Gemini API（推奨）	Python 経由の Google 公式 API です。GOOGLE_API_KEY 環境変数が必要です。
2	Gemini Web（ブラウザベース）	⚠️ リバースエンジニアリングされた Web API を使用します。API キーは不要ですが、動作しなくなる可能性があります。

API キーが使用できない場合、オプション 1 を推奨しないでください。セットアップセクションにあるキー不要の代替手順（--outline-only + 抽出 + プロンプトの引き継ぎ）を提示してください。

オプション 1：Gemini API（Python）

1. API キーを確認：GOOGLE_API_KEY または GEMINI_API_KEY 環境変数を確認します。
2. 生成スクリプトを実行：

   python3 ${SKILL_DIR}/scripts/generate-slides.py <slide-deck-dir>
   

   モデル ID はここで一度だけ記載します：gemini-3-pro-image（Nano Banana Pro、GA。旧 -preview ID は非推奨です）。必要な場合のみ --model <id> で上書きします。

スクリプトの動作（詳細はスクリプトの docstring を参照）：

• google-genai を自動インストールします。プロンプトファイルが見つからない場合はエラーで終了します（終了コードは 0 以外）。
• 失敗した生成をバックオフ付きで再試行します（合計 3 回、10 秒／15 秒のリニア間隔）。
• 生成済みのスライド（10 KB 超、画像拡張子は問わない）はスキップします。
• 各スライドをデッキのルートに保存します。抽出した図を使うスライドと同じ場所に保存されるため、マージの手順 1 回で両方を取り込めます。
• 実際の画像拡張子で保存し、webp のレスポンスは PNG に変換します（マージスクリプトが受け付けるのは png／jpg／jpeg のみです）。

オプション 2：Gemini Web スキル

同意の確認、スライドごとの呼び出し、プロキシのセットアップについては、references/gemini-web.md を参照してください。この方法には baoyu-danger-gemini-web スキルが必要であり、リバースエンジニアリングされた API に関する免責事項への明示的な同意が必要です。

ステップ 5.5：IMAGE_SOURCE の処理（図の自動抽出）

学術プレゼンテーションでは、ステップ 1 で検出した図に基づき、ステップ 2 で IMAGE_SOURCE メタデータが自動入力されます。

自動実行：

1. アウトラインを解析し、Source: extract が指定されたスライドを特定します。

2. 図のディレクトリを作成：mkdir -p figures

3. 抽出するスライドごとに、次の処理を自動的に行います。

   • メタデータから図番号、ページ、キャプションを読み取ります。
   • 図の抽出スクリプトを実行します。

     npx -y bun ${SKILL_DIR}/scripts/extract-figure.ts \
       --pdf source-paper.pdf \
       --page <page-number> \
       --output figures/figure-<N>.png
     

     注：extract-figure.ts はページ全体を高解像度 PNG としてレンダリングします。図のバウンディングボックスを自動検出して切り抜くことはありません。2 段組みのページでは両方の段が出力されます。図だけを切り出すには、--crop "x,y,width,height"（レンダリング／拡大縮小後のページ上のピクセル単位）を渡すか、PNG を開いて目視で確認し、テンプレートを適用する前に手動で切り抜いてください。
   • テンプレート適用スクリプトを実行します。

     npx -y bun ${SKILL_DIR}/scripts/apply-template.ts \
       --figure figures/figure-<N>.png \
       --title "<slide-headline>" \
       --caption "Figure <N>: <caption-text>" \
       --output <NN>-slide-<slug>.png
     

   • 「抽出済み：図 N → スライド NN」と報告します。

4. Source: generate が指定されたスライド（または IMAGE_SOURCE がないスライド）の場合：

   • AI 生成を行うため、ステップ 6 に進みます。

注：ソース PDF は出力ディレクトリに source-paper.pdf という名前で保存する必要があります。

トラブルシューティング：

• 図の検出で図を見落とした場合：アウトラインに // IMAGE_SOURCE ブロックを手動で追加します。
• 誤った図が割り当てられた場合：アウトラインの Figure: と Page: の値を編集します。
• 抽出に失敗した場合：PDF のページ番号を確認します（1 始まり）。

ページ抽出での PyMuPDF フォールバック： extract-figure.ts が「Image or Canvas expected」エラーで失敗する場合（複雑な PDF でよく発生します）、PyMuPDF を使用します。

import fitz
doc = fitz.open("source-paper.pdf")
page = doc[page_num - 1]  # 0-indexed
mat = fitz.Matrix(3, 3)  # 3x scale for high resolution
pix = page.get_pixmap(matrix=mat)
pix.save(f"extracted/page-{page_num}.png")

その後、apply-template.ts を使用してテンプレートを適用します。

ステップ 6：画像を生成する

1. ステップ 5 で選択した方法を使用します
2. ステップ 5.5 ですでに処理したスライド（Source: extract のもの）はスキップします
3. セッション ID を生成します：slides-{topic-slug}-{timestamp}
4. 残りの各スライドを同じセッション ID で生成します
5. 進捗を報告します：「X/N を生成しました」
6. 失敗した場合は自動的に再試行します（API 経由の場合：バックオフを挟んで 3 回試行。ステップ 5 を参照）

ステップ 6.5：生成画像を校正する（コンテンツの整合性）

テキストから画像を生成すると、文字がピクセルに焼き付けられ、スペル、数学記号、数値が崩れることがあります。これはこのスキルにおける最大のリスクです。確認せずに出荷しないでください。 （これは、リポジトリで共有されている引用整合性の中核 [docs/citation-integrity-core.md] をこのスキルに適用したものです。数値と主張はソースと一致していなければならず、失敗は目に見えるフラグとして示し、決して黙って置き換えてはなりません。）

生成したスライドはすべて（特に数式、表、重要な数値、非ラテン文字を含むもの）、Read を使って PNG を開き、目視で確認します。

1. スペル／表現 — 見出しと本文がアウトラインと一致し、存在しない単語や崩れた単語がないこと。
2. 数学記号 — 数式、下付き文字、ギリシャ文字、演算子が正しいこと（または含まれていないこと）。確認するまでは、モデルが誤ったものを生成したと想定してください。
3. 数値と単位 — データを示す数値がソースと完全に一致していること。

文字の崩れが見つかった場合：

• 修正または簡略化したプロンプトでそのスライドを再生成します（リスクのある用語は発音どおりに表記し、テキスト量を減らし、正確な数値はキャプションに移します）。再試行は最大 2 回です。
• 2 回再試行しても解決しない場合は、ステップ 8 の概要でそのスライドに [CHECK] フラグを付け、次のいずれかを推奨します。
  • ソース PDF から抽出した図表に置き換える（Source: extract）、または
  • 壊れやすいテキストを取り除くよう、スライドを簡略化する、または
  • 正確で編集可能な数式／データが本当に必要な資料の場合は、scholar-slides に切り替える。

数式やデータが崩れたスライドを、決して黙って納品しないでください。必ずその事実を明示してください。

ステップ 7：PPTX と PDF にまとめる

npx -y bun ${SKILL_DIR}/scripts/merge-to-pptx.ts <slide-deck-dir>
npx -y bun ${SKILL_DIR}/scripts/merge-to-pdf.ts <slide-deck-dir>

ステップ 8：出力の概要

Slide Deck Complete!

Topic: [topic]
Style: [style name]
Location: [directory path]
Slides: N total

- 01-slide-cover.png ✓ Cover
- 02-slide-intro.png ✓ Content
- 04-slide-results.png ⚠ [CHECK] math/numbers — verify or use scholar-slides
- ...
- {NN}-slide-back-cover.png ✓ Back Cover

Outline: outline.md
PPTX: {topic-slug}.pptx
PDF: {topic-slug}.pdf

ステップ 6.5 で [CHECK] フラグを付けたスライドをすべて明記し、文字、数式、データが崩れている可能性のあるスライドと、その修正方法がユーザーに分かるようにしてください。

スライドの変更

以下については references/modification-guide.md を参照してください。

• 1 枚のスライドを編集するワークフロー
• スライドを追加する（番号を振り直す）
• スライドを削除する（番号を振り直す）
• ファイル名の規則

画像生成の依存関係

Gemini API（オプション 1 — 推奨）

必要なもの：

• GOOGLE_API_KEY または GEMINI_API_KEY 環境変数
• pip を含む Python 3.8 以降
• google-genai パッケージ（スクリプトによって自動インストールされます）

モデル ID：ステップ 5 で一度だけ指定します。

Gemini Web スキル（オプション 2）

references/gemini-web.md を参照してください。baoyu-danger-gemini-web スキル、Google アカウントにログイン済みの Chrome、およびユーザーの同意が必要です。

PDF 図版の抽出

必要なもの（cd ${SKILL_DIR}/scripts && npm install でインストール）：

• 主な方法：pdfjs-dist npm パッケージ（Node.js では legacy ビルドを使用）
• extract-figure.ts / apply-template.ts 用の canvas npm パッケージ
• 代替方法：pymupdf Python パッケージ（複雑な PDF でより信頼性があります）

参考資料

現在のステージに対応する参考ファイルのみを読んでください。references/ をまとめて読み込まないでください。

ファイル	読むタイミング
references/analysis-framework.md	ステップ 1 — 詳細なコンテンツ分析、IMAGE_SOURCE のマッピングルール
references/style-selection.md	ステップ 1/3 — スタイルギャラリーと自動選択（アカデミックなシグナルに関する注意を含む）
references/outline-template.md	ステップ 2 — アウトラインの構成と STYLE_INSTRUCTIONS の形式
references/layout-gallery.md	ステップ 2 — スライドごとの Layout: ヒント
references/base-prompt.md	ステップ 4 — 画像生成用の基本プロンプト
references/gemini-web.md	ステップ 5、オプション 2 — 同意、呼び出し、プロキシ
references/modification-guide.md	納品後の編集 — スライドの追加・削除・番号変更のワークフロー
references/content-rules.md	コンテンツとスタイルのガイドライン
references/figure-container-template.md	ステップ 5.5 — 抽出した図のコンテナのビジュアル仕様
references/styles/<style>.md	選択したスタイルの完全な仕様

注意事項

画像生成

• Gemini API：推奨されます。安定していて信頼性が高く、API キーが必要です
• Gemini Web：API キーは不要ですが、リバースエンジニアリングされた API を使用するため、アカウントにリスクがあります
• 生成時間：スライド 1 枚につき 10～30 秒
• 失敗した場合は自動的に再試行します（API 経由の場合：バックオフを挟んで 3 回試行）
• セッション ID を使用してスタイルの一貫性を保ちます

コンテンツガイドライン

• 公人の扱いには、センシティブな内容を避けた表現を使用してください
• どちらの方法も Gemini の画像モデルを使用しますが、Web 経由ではモデルのバージョンを制御できません。Google のデプロイに従うため、API 経由の場合とは異なるバージョンになる可能性があります