paper-slide-deck

•

512705 months ago

Generate professional slide deck images from academic papers and content. Creates comprehensive outlines with style instructions, auto-detects figures from PDFs, then generates individual slide images. Use when user asks to "create slides", "make a presentation", "generate deck", or "slide deck" for papers.

Quick Install

npxskills add luwill/research-skills--skill paper-slide-deck

Instructions

Paper Slide Deck Generator

Transform academic papers and content into professional slide deck images with automatic figure extraction.

Usage

/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

Setup (one-time)

The TypeScript scripts (merge-to-*, detect-figures, extract-figure, apply-template) need Node dependencies. Install them once:

cd ${SKILL_DIR}/scripts && npm install

This installs canvas, pdfjs-dist, pptxgenjs, and pdf-lib (a package-lock.json pins versions). If a script exits with missing Node dependency "<name>", run the command above. The Python generator (generate-slides.py) auto-installs google-genai on first run.

Also install PyMuPDF (pip install pymupdf) — it is the reliable fallback for extracting figures from pages that embed bitmaps (X-rays, CAM heatmaps, photographs), where the pdfjs + canvas path in extract-figure.ts fails with Error: Image or Canvas expected. For medical-imaging papers this is the common case, not the exception, so treat PyMuPDF as required, not optional.

Image generation & no-API-key path

Image generation needs either a GOOGLE_API_KEY/GEMINI_API_KEY (Gemini API) or the Gemini Web skill. If no key and no web option is available, the skill still works in a degraded mode — do not abort:

Run with --outline-only to produce the outline + prompts (no images).
For a source PDF, extract real figures/tables with detect-figures.ts + extract-figure.ts + apply-template.ts (no API key needed — pure rendering).
Merge whatever slides exist (extract-sourced pages) into PPTX/PDF, and hand the prompts/ back to the user to generate images later when a key is available.

Script Directory

Important: All scripts are located in the scripts/ subdirectory of this skill.

Agent Execution Instructions:

Determine this SKILL.md file's directory path as SKILL_DIR
Script path = ${SKILL_DIR}/scripts/<script-name>.ts
Replace all ${SKILL_DIR} in this document with the actual path

Script Reference:

Script	Purpose
`scripts/generate-slides.py`	Generate AI slides via Gemini API (Python)
`scripts/merge-to-pptx.ts`	Merge slides into PowerPoint
`scripts/merge-to-pdf.ts`	Merge slides into PDF
`scripts/detect-figures.ts`	Auto-detect figures/tables in PDF (heuristic; verify pages)
`scripts/extract-figure.ts`	Render a full PDF page to PNG (optional `--crop`; PyMuPDF fallback)
`scripts/apply-template.ts`

Options

Option	Description
`--style <name>`	Visual style (see Style Gallery)
`--audience <type>`	Target audience: beginners, intermediate, experts, executives, general
`--lang <code>`	Output language (en, zh, ja, etc.)
`--slides <number>`	Target slide count
`--outline-only`	Generate outline only, skip image generation

Style Gallery

Style	Description	Best For
`academic-paper`	Clean professional, precise charts	Academic-style visuals, technical handouts (for a faithful editable talk use scholar-slides)
`blueprint` (Default)	Technical schematics, grid texture	Architecture, system design
`chalkboard`	Black chalkboard, colorful chalk	Education, tutorials, classroom
`notion`	SaaS dashboard, card-based layouts	Product demos, SaaS, B2B
`bold-editorial`	Magazine cover, bold typography, dark

Auto Style Selection

Content Signals	Selected Style
paper, thesis, defense, conference, ieee, acm, icml, neurips, cvpr, acl, aaai, iclr	`academic-paper`
tutorial, learn, education, guide, intro, beginner	`sketch-notes`
classroom, teaching, school, chalkboard, blackboard	`chalkboard`
architecture, system, data, analysis, technical	`blueprint`
creative, children, kids, cute, illustration	`vector-illustration`
briefing, bilingual, infographic, concept	`intuition-machine`

Academic-signal caution: When the content matches academic-paper signals (paper/thesis/neurips/cvpr/icml/…), this skill still bakes text into an image, so equations, result tables, and exact numbers may be garbled. Extract real figures/tables from the source PDF (Source: extract) rather than letting the model redraw them, and if the deck needs faithful, editable formulas/data, tell the user to use scholar-slides instead.

Layout Gallery

Optional layout hints for individual slides. Specify in outline's // LAYOUT section.

Slide-Specific Layouts

Layout	Description	Best For
`title-hero`	Large centered title + subtitle	Cover slides, section breaks
`quote-callout`	Featured quote with attribution	Testimonials, key insights
`key-stat`	Single large number as focal point	Impact statistics, metrics
`split-screen`	Half image, half text	Feature highlights, comparisons
`icon-grid`	Grid of icons with labels	Features, capabilities, benefits

Infographic-Derived Layouts

Layout	Description	Best For
`linear-progression`	Sequential flow left-to-right	Timelines, step-by-step
`binary-comparison`	Side-by-side A vs B	Before/after, pros-cons
`comparison-matrix`	Multi-factor grid	Feature comparisons
`hierarchical-layers`	Pyramid or stacked levels	Priority, importance
`hub-spoke`	Central node with radiating items	Concept maps, ecosystems

Academic-Specific Layouts

Layout	Description	Best For
`paper-title`	Title, authors, affiliations, venue	Conference paper cover
`outline-agenda`	Numbered section list with highlights	Talk structure overview
`methods-diagram`	Central architecture/pipeline diagram	Methods, system design
`results-chart`	Chart area + data annotations	Quantitative results
`equation-focus`	Centered equation + variable definitions	Mathematical derivations

Usage: Add Layout: <name> in slide's // LAYOUT section to guide visual composition.

Design Philosophy

This deck is designed for reading and sharing, not live presentation:

Each slide must be self-explanatory without verbal commentary
Structure content for logical flow when scrolling
Include all necessary context within each slide
Optimize for social media sharing and offline reading

File Management

Output Directory

Each session creates an independent directory named by content slug:

slide-deck/{topic-slug}/
├── source-{slug}.{ext}    # Source files (text, images, etc.)
├── outline.md
├── outline-{style}.md     # Style variant outlines
├── prompts/
│   └── 01-slide-cover.md, 02-slide-{slug}.md, ...
├── 01-slide-cover.png, 02-slide-{slug}.png, ...
├── {topic-slug}.pptx
└── {topic-slug}.pdf

Slug Generation:

Extract main topic from content (2-4 words, kebab-case)
Example: "Introduction to Machine Learning" → intro-machine-learning

Conflict Resolution

If slide-deck/{topic-slug}/ already exists:

Append timestamp: {topic-slug}-YYYYMMDD-HHMMSS
Example: intro-ml exists → intro-ml-20260118-143052

Source Files

Copy all sources with naming source-{slug}.{ext}:

source-article.md (main text content)
source-diagram.png (image from conversation)
source-data.xlsx (additional file)

Multiple sources supported: text, images, files from conversation.

Workflow

Step 1: Analyze Content

Save source content (if pasted, save as source.md)
Follow references/analysis-framework.md for deep content analysis
Determine style (use --style or auto-select from signals)
Detect languages (source vs. user preference)
Plan slide count (--slides or dynamic)
For academic papers (PDF with figures): Run automatic figure detection:
```
npx -y bun ${SKILL_DIR}/scripts/detect-figures.ts --pdf source-paper.pdf --output figures.json
```
This outputs a JSON file with all detected figures/tables, their page numbers, and captions.

Caption detection is heuristic — verify, especially the first-page teaser. The line-anchored Figure N matcher reliably finds captions that sit on their own line (single-column layouts), but — which is often the paper's most important architecture/overview figure. After running detect-figures, cross-check the source's explicitly: if the paper's text references a that is absent from , add it manually via an block and extract it with the PyMuPDF fallback. Do not assume is complete.

Step 2: Generate Outline Variants

Generate 3 style variant outlines based on content analysis
Follow references/outline-template.md for structure
Auto-populate IMAGE_SOURCE for academic papers:
- Read figures.json from Step 1
- Map figures to slides using rules in references/analysis-framework.md Section 8
- Automatically add // IMAGE_SOURCE blocks to appropriate slides:
  - Architecture/pipeline figures → Methods slides (Source: extract)
  - Results tables → Quantitative results slides (Source: extract)
  - Comparison images → Qualitative results slides (Source: extract)
  - Conceptual/simple diagrams → Leave for AI generation (Source: generate or omit)

Step 3: User Confirmation

Single AskUserQuestion with all applicable options:

Question	When to Ask
Style variant	Always (3 options + custom)
Language	Only if source ≠ user language

After selection:

Copy selected outline-{style}.md to outline.md
Regenerate in different language if requested
User may edit outline.md for fine-tuning

If --outline-only, stop here.

Step 4: Generate Prompts

Read references/base-prompt.md
Combine with style instructions from outline
Add slide-specific content
If Layout: specified in outline, include layout guidance in prompt:
- Reference layout characteristics for image composition
- Example: Layout: hub-spoke → "Central concept in middle with related items radiating outward"
Save to prompts/ directory

Step 5: Image Generation Method Selection

Before generating images, ask user to choose generation method:

Use AskUserQuestion with options:

Option	Label	Description
1	Gemini API (Recommended)	Official Google API via Python. Requires GOOGLE_API_KEY env var.
2	Gemini Web (Browser-based)	⚠️ Uses reverse-engineered web API. No API key needed but may break.

Based on selection:

Option 1: Gemini API (Python)

Verify API key: Check GOOGLE_API_KEY or GEMINI_API_KEY environment variable
Run generation script:
```
python3 ${SKILL_DIR}/scripts/generate-slides.py <slide-deck-dir>
```
The default model is gemini-3-pro-image (Nano Banana Pro, GA). Override with --model <id> if needed. The older gemini-3-pro-image-preview id is deprecated.

Script Features:

Auto-installs google-genai package if missing
Reads prompt files as *.md (or *.txt) from prompts/
Errors out (non-zero) if no prompt files are found — no silent "nothing to do"
Retry logic with exponential backoff (3 retries)
Sets response_modalities=["IMAGE"] so the model returns image parts
Skips already-generated slides (> 10KB, any image extension)
Writes each slide to the deck root (e.g. 01-slide-cover.png), the same place extracted-figure slides land — so one merge step picks up both
Saves with the real image extension (Gemini often returns JPEG even when PNG is requested → saved as .jpg, never a mislabeled .png)
Supports custom model via flag

Troubleshooting:

If server disconnection errors occur, script auto-retries
For persistent failures, re-run the script (it skips completed slides)
Check API quota if many failures occur

Option 2: Gemini Web Skill

Consent Check: Read consent file at:
- Windows: $APPDATA/baoyu-skills/gemini-web/consent.json
- macOS: ~/Library/Application Support/baoyu-skills/gemini-web/consent.json
- Linux: ~/.local/share/baoyu-skills/gemini-web/consent.json

If no consent or version mismatch, display disclaimer and ask:

⚠️ DISCLAIMER: This uses a reverse-engineered Gemini Web API (NOT official).
Risks: May break anytime, no support, possible account risk.

For each slide, run:

npx -y bun ${GEMINI_WEB_SKILL_DIR}/scripts/main.ts \
  --promptfiles prompts/01-slide-cover.md \
  --image 01-slide-cover.png \
  --sessionId slides-{topic-slug}-{timestamp}

Where GEMINI_WEB_SKILL_DIR = path to skill directory.

Step 5.5: Process IMAGE_SOURCE (Automatic Figure Extraction)

For academic presentations, IMAGE_SOURCE metadata was auto-populated in Step 2 based on figure detection from Step 1.

Automatic Execution:

Parse outline to identify slides with Source: extract
Create figures directory: mkdir -p figures
For each extract slide, automatically:
- Read the Figure number, Page, and Caption from metadata
- Run figure extraction script:
```
npx -y bun ${SKILL_DIR}/scripts/extract-figure.ts \
  --pdf source-paper.pdf \
  --page <page-number> \
  --output figures/figure-<N>.png
```
  Note: extract-figure.ts renders the entire page to a high-resolution PNG — it does not auto-detect or crop a single figure's bounding box. On a two-column page you will get both columns. To isolate one figure, either pass --crop "x,y,width,height" (pixels in the rendered/scaled page) or open the PNG, confirm it visually, and crop manually before applying the template.
- Run template application script:
```
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
```

Note: Source PDF must be saved as source-paper.pdf in output directory.

Troubleshooting:

If figure detection missed a figure: manually add // IMAGE_SOURCE block to outline
If wrong figure mapped: edit the Figure: and Page: values in outline
If extraction fails: check PDF page number (1-indexed)

PyMuPDF Fallback for Page Extraction: If extract-figure.ts fails with "Image or Canvas expected" error (common with complex PDFs), use 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")

Then apply template using apply-template.ts.

Step 6: Generate Images

Use selected method from Step 5
Skip slides already processed in Step 5.5 (those with Source: extract)
Generate session ID: slides-{topic-slug}-{timestamp}
Generate each remaining slide with same session ID
Report progress: "Generated X/N"
Auto-retry once on generation failure

Step 6.5: Proofread Generated Images (Content Integrity)

Text-to-image bakes text into pixels and will garble spelling, math symbols, and numbers — this is the single biggest risk of this skill. Do not ship unchecked.

For every generated slide (especially any with equations, tables, key numbers, or non-Latin text), use Read to open the PNG and visually check:

Spelling / wording — headline and body text match the outline, no invented or mangled words.
Math & symbols — equations, subscripts, Greek letters, operators are correct (or absent). Assume the model got them wrong until you confirm otherwise.
Numbers & units — any figure that carries data matches the source exactly.

If garbling is found:

Regenerate that slide with a corrected/simplified prompt (spell risky terms phonetically, reduce text density, move exact numbers to a caption). Max 2 retries.
If it still fails after 2 retries, flag the slide [CHECK] in the Step 8 summary and recommend one of:
- Replace with an extracted figure/table from the source PDF (Source: extract), or
- Simplify the slide to remove the fragile text, or
- For a deck that genuinely needs faithful, editable formulas/data, switch to scholar-slides.

Never silently deliver a slide with garbled math or data — always surface it.

Step 7: Merge to PPTX and 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>

Step 8: Output Summary

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

List any [CHECK]-flagged slides (from Step 6.5) explicitly so the user knows which slides may contain garbled text/math/data and how to remediate them.

Slide Modification

See references/modification-guide.md for:

Edit single slide workflow
Add new slide (with renumbering)
Delete slide (with renumbering)
File naming conventions

Image Generation Dependencies

Gemini API (Option 1 - Recommended)

Requires:

GOOGLE_API_KEY or GEMINI_API_KEY environment variable
Python 3.8+ with pip
google-genai package (auto-installed by script)

Model: gemini-3-pro-image (default; Nano Banana Pro, GA). The older gemini-3-pro-image-preview id is deprecated — override with --model only if needed.

Gemini Web Skill (Option 2)

Requires:

baoyu-danger-gemini-web skill installed at .claude/skills/baoyu-danger-gemini-web
Google Chrome browser with logged-in Google account
User consent for reverse-engineered API disclaimer

PDF Figure Extraction

Requires (install via cd ${SKILL_DIR}/scripts && npm install):

Primary: pdfjs-dist npm package (use legacy build for Node.js)
canvas npm package for extract-figure.ts / apply-template.ts
Fallback: pymupdf Python package (more reliable for complex PDFs)

References

File	Content
`references/analysis-framework.md`	Deep content analysis for presentations
`references/outline-template.md`	Outline structure and STYLE_INSTRUCTIONS format
`references/modification-guide.md`	Edit, add, delete slide workflows
`references/content-rules.md`	Content and style guidelines
`references/base-prompt.md`	Base prompt for image generation
`references/figure-container-template.md`

Notes

Image Generation

Nano Banana Pro API: Recommended. Stable, reliable, requires API key
Gemini Web: No API key needed, but uses reverse-engineered API with account risk
Generation time: 10-30 seconds per slide
Auto-retry once on generation failure
Maintain style consistency via session ID

Content Guidelines

Use stylized alternatives for sensitive public figures
Both methods use the same underlying Gemini model for image generation

Extension Support

Custom styles and configurations via EXTEND.md.

Check paths (priority order):

.paper-skills/paper-slide-deck/EXTEND.md (project)
~/.paper-skills/paper-slide-deck/EXTEND.md (user)

If found, load before Step 1. Extension content overrides defaults.

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885

Paper Slide Deck Generator

Transform academic papers and content into professional slide deck images with automatic figure extraction.

Usage

/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

Setup (one-time)

The TypeScript scripts (merge-to-*, detect-figures, extract-figure, apply-template) need Node dependencies. Install them once:

cd ${SKILL_DIR}/scripts && npm install

Image generation & no-API-key path

Run with --outline-only to produce the outline + prompts (no images).
For a source PDF, extract real figures/tables with detect-figures.ts + extract-figure.ts + apply-template.ts (no API key needed — pure rendering).
Merge whatever slides exist (extract-sourced pages) into PPTX/PDF, and hand the prompts/ back to the user to generate images later when a key is available.

Script Directory

Important: All scripts are located in the scripts/ subdirectory of this skill.

Agent Execution Instructions:

Determine this SKILL.md file's directory path as SKILL_DIR
Script path = ${SKILL_DIR}/scripts/<script-name>.ts
Replace all ${SKILL_DIR} in this document with the actual path

Script Reference:

Script	Purpose
`scripts/generate-slides.py`	Generate AI slides via Gemini API (Python)
`scripts/merge-to-pptx.ts`	Merge slides into PowerPoint
`scripts/merge-to-pdf.ts`	Merge slides into PDF
`scripts/detect-figures.ts`	Auto-detect figures/tables in PDF (heuristic; verify pages)
`scripts/extract-figure.ts`	Render a full PDF page to PNG (optional `--crop`; PyMuPDF fallback)
`scripts/apply-template.ts`

Options

Option	Description
`--style <name>`	Visual style (see Style Gallery)
`--audience <type>`	Target audience: beginners, intermediate, experts, executives, general
`--lang <code>`	Output language (en, zh, ja, etc.)
`--slides <number>`	Target slide count
`--outline-only`	Generate outline only, skip image generation

Style Gallery

Style	Description	Best For
`academic-paper`	Clean professional, precise charts	Academic-style visuals, technical handouts (for a faithful editable talk use scholar-slides)
`blueprint` (Default)	Technical schematics, grid texture	Architecture, system design
`chalkboard`	Black chalkboard, colorful chalk	Education, tutorials, classroom
`notion`	SaaS dashboard, card-based layouts	Product demos, SaaS, B2B
`bold-editorial`	Magazine cover, bold typography, dark

Auto Style Selection

Content Signals	Selected Style
paper, thesis, defense, conference, ieee, acm, icml, neurips, cvpr, acl, aaai, iclr	`academic-paper`
tutorial, learn, education, guide, intro, beginner	`sketch-notes`
classroom, teaching, school, chalkboard, blackboard	`chalkboard`
architecture, system, data, analysis, technical	`blueprint`
creative, children, kids, cute, illustration	`vector-illustration`
briefing, bilingual, infographic, concept	`intuition-machine`

Academic-signal caution: When the content matches academic-paper signals (paper/thesis/neurips/cvpr/icml/…), this skill still bakes text into an image, so equations, result tables, and exact numbers may be garbled. Extract real figures/tables from the source PDF (Source: extract) rather than letting the model redraw them, and if the deck needs faithful, editable formulas/data, tell the user to use scholar-slides instead.

Layout Gallery

Optional layout hints for individual slides. Specify in outline's // LAYOUT section.

Slide-Specific Layouts

Layout	Description	Best For
`title-hero`	Large centered title + subtitle	Cover slides, section breaks
`quote-callout`	Featured quote with attribution	Testimonials, key insights
`key-stat`	Single large number as focal point	Impact statistics, metrics
`split-screen`	Half image, half text	Feature highlights, comparisons
`icon-grid`	Grid of icons with labels	Features, capabilities, benefits

Infographic-Derived Layouts

Layout	Description	Best For
`linear-progression`	Sequential flow left-to-right	Timelines, step-by-step
`binary-comparison`	Side-by-side A vs B	Before/after, pros-cons
`comparison-matrix`	Multi-factor grid	Feature comparisons
`hierarchical-layers`	Pyramid or stacked levels	Priority, importance
`hub-spoke`	Central node with radiating items	Concept maps, ecosystems

Academic-Specific Layouts

Layout	Description	Best For
`paper-title`	Title, authors, affiliations, venue	Conference paper cover
`outline-agenda`	Numbered section list with highlights	Talk structure overview
`methods-diagram`	Central architecture/pipeline diagram	Methods, system design
`results-chart`	Chart area + data annotations	Quantitative results
`equation-focus`	Centered equation + variable definitions	Mathematical derivations

Usage: Add Layout: <name> in slide's // LAYOUT section to guide visual composition.

Design Philosophy

This deck is designed for reading and sharing, not live presentation:

Each slide must be self-explanatory without verbal commentary
Structure content for logical flow when scrolling
Include all necessary context within each slide
Optimize for social media sharing and offline reading

File Management

Output Directory

Each session creates an independent directory named by content slug:

slide-deck/{topic-slug}/
├── source-{slug}.{ext}    # Source files (text, images, etc.)
├── outline.md
├── outline-{style}.md     # Style variant outlines
├── prompts/
│   └── 01-slide-cover.md, 02-slide-{slug}.md, ...
├── 01-slide-cover.png, 02-slide-{slug}.png, ...
├── {topic-slug}.pptx
└── {topic-slug}.pdf

Slug Generation:

Extract main topic from content (2-4 words, kebab-case)
Example: "Introduction to Machine Learning" → intro-machine-learning

Conflict Resolution

If slide-deck/{topic-slug}/ already exists:

Append timestamp: {topic-slug}-YYYYMMDD-HHMMSS
Example: intro-ml exists → intro-ml-20260118-143052

Source Files

Copy all sources with naming source-{slug}.{ext}:

source-article.md (main text content)
source-diagram.png (image from conversation)
source-data.xlsx (additional file)

Multiple sources supported: text, images, files from conversation.

Workflow

Step 1: Analyze Content

Save source content (if pasted, save as source.md)
Follow references/analysis-framework.md for deep content analysis
Determine style (use --style or auto-select from signals)
Detect languages (source vs. user preference)
Plan slide count (--slides or dynamic)
For academic papers (PDF with figures): Run automatic figure detection:
```
npx -y bun ${SKILL_DIR}/scripts/detect-figures.ts --pdf source-paper.pdf --output figures.json
```
This outputs a JSON file with all detected figures/tables, their page numbers, and captions.

Caption detection is heuristic — verify, especially the first-page teaser. The line-anchored Figure N matcher reliably finds captions that sit on their own line (single-column layouts), but — which is often the paper's most important architecture/overview figure. After running detect-figures, cross-check the source's explicitly: if the paper's text references a that is absent from , add it manually via an block and extract it with the PyMuPDF fallback. Do not assume is complete.

Step 2: Generate Outline Variants

Generate 3 style variant outlines based on content analysis
Follow references/outline-template.md for structure
Auto-populate IMAGE_SOURCE for academic papers:
- Read figures.json from Step 1
- Map figures to slides using rules in references/analysis-framework.md Section 8
- Automatically add // IMAGE_SOURCE blocks to appropriate slides:
  - Architecture/pipeline figures → Methods slides (Source: extract)
  - Results tables → Quantitative results slides (Source: extract)
  - Comparison images → Qualitative results slides (Source: extract)
  - Conceptual/simple diagrams → Leave for AI generation (Source: generate or omit)

Step 3: User Confirmation

Single AskUserQuestion with all applicable options:

Question	When to Ask
Style variant	Always (3 options + custom)
Language	Only if source ≠ user language

After selection:

Copy selected outline-{style}.md to outline.md
Regenerate in different language if requested
User may edit outline.md for fine-tuning

If --outline-only, stop here.

Step 4: Generate Prompts

Read references/base-prompt.md
Combine with style instructions from outline
Add slide-specific content
If Layout: specified in outline, include layout guidance in prompt:
- Reference layout characteristics for image composition
- Example: Layout: hub-spoke → "Central concept in middle with related items radiating outward"
Save to prompts/ directory

Step 5: Image Generation Method Selection

Before generating images, ask user to choose generation method:

Use AskUserQuestion with options:

Option	Label	Description
1	Gemini API (Recommended)	Official Google API via Python. Requires GOOGLE_API_KEY env var.
2	Gemini Web (Browser-based)	⚠️ Uses reverse-engineered web API. No API key needed but may break.

Based on selection:

Option 1: Gemini API (Python)

Verify API key: Check GOOGLE_API_KEY or GEMINI_API_KEY environment variable
Run generation script:
```
python3 ${SKILL_DIR}/scripts/generate-slides.py <slide-deck-dir>
```
The default model is gemini-3-pro-image (Nano Banana Pro, GA). Override with --model <id> if needed. The older gemini-3-pro-image-preview id is deprecated.

Script Features:

Auto-installs google-genai package if missing
Reads prompt files as *.md (or *.txt) from prompts/
Errors out (non-zero) if no prompt files are found — no silent "nothing to do"
Retry logic with exponential backoff (3 retries)
Sets response_modalities=["IMAGE"] so the model returns image parts
Skips already-generated slides (> 10KB, any image extension)
Writes each slide to the deck root (e.g. 01-slide-cover.png), the same place extracted-figure slides land — so one merge step picks up both
Saves with the real image extension (Gemini often returns JPEG even when PNG is requested → saved as .jpg, never a mislabeled .png)
Supports custom model via flag

Troubleshooting:

If server disconnection errors occur, script auto-retries
For persistent failures, re-run the script (it skips completed slides)
Check API quota if many failures occur

Option 2: Gemini Web Skill

Consent Check: Read consent file at:
- Windows: $APPDATA/baoyu-skills/gemini-web/consent.json
- macOS: ~/Library/Application Support/baoyu-skills/gemini-web/consent.json
- Linux: ~/.local/share/baoyu-skills/gemini-web/consent.json

If no consent or version mismatch, display disclaimer and ask:

⚠️ DISCLAIMER: This uses a reverse-engineered Gemini Web API (NOT official).
Risks: May break anytime, no support, possible account risk.

For each slide, run:

npx -y bun ${GEMINI_WEB_SKILL_DIR}/scripts/main.ts \
  --promptfiles prompts/01-slide-cover.md \
  --image 01-slide-cover.png \
  --sessionId slides-{topic-slug}-{timestamp}

Where GEMINI_WEB_SKILL_DIR = path to skill directory.

Step 5.5: Process IMAGE_SOURCE (Automatic Figure Extraction)

For academic presentations, IMAGE_SOURCE metadata was auto-populated in Step 2 based on figure detection from Step 1.

Automatic Execution:

Parse outline to identify slides with Source: extract
Create figures directory: mkdir -p figures
For each extract slide, automatically:
- Read the Figure number, Page, and Caption from metadata
- Run figure extraction script:
```
npx -y bun ${SKILL_DIR}/scripts/extract-figure.ts \
  --pdf source-paper.pdf \
  --page <page-number> \
  --output figures/figure-<N>.png
```
  Note: extract-figure.ts renders the entire page to a high-resolution PNG — it does not auto-detect or crop a single figure's bounding box. On a two-column page you will get both columns. To isolate one figure, either pass --crop "x,y,width,height" (pixels in the rendered/scaled page) or open the PNG, confirm it visually, and crop manually before applying the template.
- Run template application script:
```
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
```

Note: Source PDF must be saved as source-paper.pdf in output directory.

Troubleshooting:

If figure detection missed a figure: manually add // IMAGE_SOURCE block to outline
If wrong figure mapped: edit the Figure: and Page: values in outline
If extraction fails: check PDF page number (1-indexed)

PyMuPDF Fallback for Page Extraction: If extract-figure.ts fails with "Image or Canvas expected" error (common with complex PDFs), use 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")

Then apply template using apply-template.ts.

Step 6: Generate Images

Use selected method from Step 5
Skip slides already processed in Step 5.5 (those with Source: extract)
Generate session ID: slides-{topic-slug}-{timestamp}
Generate each remaining slide with same session ID
Report progress: "Generated X/N"
Auto-retry once on generation failure

Step 6.5: Proofread Generated Images (Content Integrity)

Text-to-image bakes text into pixels and will garble spelling, math symbols, and numbers — this is the single biggest risk of this skill. Do not ship unchecked.

For every generated slide (especially any with equations, tables, key numbers, or non-Latin text), use Read to open the PNG and visually check:

Spelling / wording — headline and body text match the outline, no invented or mangled words.
Math & symbols — equations, subscripts, Greek letters, operators are correct (or absent). Assume the model got them wrong until you confirm otherwise.
Numbers & units — any figure that carries data matches the source exactly.

If garbling is found:

Regenerate that slide with a corrected/simplified prompt (spell risky terms phonetically, reduce text density, move exact numbers to a caption). Max 2 retries.
If it still fails after 2 retries, flag the slide [CHECK] in the Step 8 summary and recommend one of:
- Replace with an extracted figure/table from the source PDF (Source: extract), or
- Simplify the slide to remove the fragile text, or
- For a deck that genuinely needs faithful, editable formulas/data, switch to scholar-slides.

Never silently deliver a slide with garbled math or data — always surface it.

Step 7: Merge to PPTX and 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>

Step 8: Output Summary

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

List any [CHECK]-flagged slides (from Step 6.5) explicitly so the user knows which slides may contain garbled text/math/data and how to remediate them.

Slide Modification

See references/modification-guide.md for:

Edit single slide workflow
Add new slide (with renumbering)
Delete slide (with renumbering)
File naming conventions

Image Generation Dependencies

Gemini API (Option 1 - Recommended)

Requires:

GOOGLE_API_KEY or GEMINI_API_KEY environment variable
Python 3.8+ with pip
google-genai package (auto-installed by script)

Model: gemini-3-pro-image (default; Nano Banana Pro, GA). The older gemini-3-pro-image-preview id is deprecated — override with --model only if needed.

Gemini Web Skill (Option 2)

Requires:

baoyu-danger-gemini-web skill installed at .claude/skills/baoyu-danger-gemini-web
Google Chrome browser with logged-in Google account
User consent for reverse-engineered API disclaimer

PDF Figure Extraction

Requires (install via cd ${SKILL_DIR}/scripts && npm install):

Primary: pdfjs-dist npm package (use legacy build for Node.js)
canvas npm package for extract-figure.ts / apply-template.ts
Fallback: pymupdf Python package (more reliable for complex PDFs)

References

File	Content
`references/analysis-framework.md`	Deep content analysis for presentations
`references/outline-template.md`	Outline structure and STYLE_INSTRUCTIONS format
`references/modification-guide.md`	Edit, add, delete slide workflows
`references/content-rules.md`	Content and style guidelines
`references/base-prompt.md`	Base prompt for image generation
`references/figure-container-template.md`

Notes

Image Generation

Nano Banana Pro API: Recommended. Stable, reliable, requires API key
Gemini Web: No API key needed, but uses reverse-engineered API with account risk
Generation time: 10-30 seconds per slide
Auto-retry once on generation failure
Maintain style consistency via session ID

Content Guidelines

Use stylized alternatives for sensitive public figures
Both methods use the same underlying Gemini model for image generation

Extension Support

Custom styles and configurations via EXTEND.md.

Check paths (priority order):

.paper-skills/paper-slide-deck/EXTEND.md (project)
~/.paper-skills/paper-slide-deck/EXTEND.md (user)

If found, load before Step 1. Extension content overrides defaults.