paper2slides

name	paper2slides
description	Generate a show-ready journal club presentation from a scientific paper PDF using the paper2slides library and agent-driven scientific comprehension.

paper2slides — Agent-Driven Journal Club Presentations

Overview

This skill transforms a scientific paper PDF into a show-ready, curated Reveal.js presentation with speaker notes. It combines two layers:

1. Mechanical layer — the paper2slides Python library extracts figures, segments panels, and scaffolds a raw Reveal.js deck.
2. Intelligence layer — you, the agent, read the paper, understand the science, curate the slide deck, write titles/captions, and compose speaker notes.

The mechanical extraction alone produces a figure dump. The agent's job is to turn that into a coherent, PhD-level journal club talk.

---

Prerequisites

The paper2slides library must be installed. If the library source is available locally:

cd <path_to_paper2slides_library> && pip install -e .

Otherwise install from the packaged distribution:

pip install paper2slides

Required Python packages (auto-installed): pymupdf, pillow, numpy, jinja2, click

---

Workflow (5 Phases)

Phase 1: Extract & Segment (Mechanical)

Run the paper2slides CLI to extract figures and segment panels:

paper2slides "<path/to/paper.pdf>" -o "<output_dir>"

This produces:

• <output_dir>/assets/img/panels/fig1a.png, fig1b.png, ... — individual panel images
• <output_dir>/index.html — a raw, uncurated Reveal.js deck (figure dump)
• <output_dir>/assets/css/style.css — slate + accented theme with expanded font choices, high-contrast body text, per-aim color tokens, feature-family badge colors, and ready-made component classes for aim-flow / info-row-3 / taxonomy-grid / compare-grid / criteria-grid / badges / schematics

Verify: Check the terminal output for the number of figures and panels extracted. If zero figures found, the PDF may use vector graphics — consider alternatives like screenshots.

Phase 2: Read & Comprehend the Paper

Use PyMuPDF to extract and read the paper text programmatically:

import fitz
doc = fitz.open("<path/to/paper.pdf>")
for i in range(len(doc)):
    page = doc[i]
    text = page.get_text('text')
    print(f'=== PAGE {i+1} ===')
    print(text)
doc.close()

As you read, identify:

• Title, authors, journal, year — for the title slide
• Core hypothesis/question — what problem does the paper solve?
• Method/approach — what's the key technique or innovation?
• Key results — which figures tell the most important story?
• Validation/proof — structural, functional, or statistical evidence
• Applications — practical implications
• Limitations & future directions — for the discussion slide

Phase 3: Inspect Extracted Panels

Open the extracted panel images in the browser to understand what each one contains:

file://<output_dir>/assets/img/panels/

For each figure number, identify:

• Which panels show structural data (protein structures, cryo-EM, etc.)
• Which show quantitative data (bar charts, scatter plots, correlations)
• Which show qualitative data (gels, blots, microscopy)
• Which panels are most important for the narrative

Create a mental mapping: figNx.png → "what this panel shows" → "which slide it belongs on"

Phase 4: Build the Curated Presentation

Create a new index.html in a show_ready/ subdirectory using the reference template structure below. The presentation should follow this structure:

Slide Structure (15–25 slides for a typical paper)

Slide Type	Count	Purpose
Title	1	Paper title, authors, journal, date
Outline	1	Numbered list of talk sections
Background	1–3	Context, prior work, the problem
Method	1–2	Key innovation / workflow
Validation	3–6	Core results with figures
Application	2–4	Deep dive into the primary application
Quantitative	1–2	Correlations, statistics, benchmarking
Takeaways	1	Bullet-point summary
Discussion	1	Limitations, future directions, discussion Qs
Thank You	1	Close + references/code links

HTML Patterns

Single figure slide:

<section>
    <h2>Slide Title</h2>
    <div class="figure-frame" data-fig="fig2a">
        <img src="assets/img/panels/fig2a.png" alt="Description">
    </div>
    <div class="figure-caption">Figure 2A: Brief caption</div>
    <aside class="notes">
        Speaker notes go here. Write 3-6 sentences explaining what the figure shows,
        why it matters, and what to emphasize to the audience.
    </aside>
</section>

Two-figure comparison slide:

<section>
    <h2>Slide Title</h2>
    <div class="figure-row">
        <div>
            <div class="figure-frame" data-fig="fig3a">
                <img src="assets/img/panels/fig3a.png" alt="Description">
            </div>
            <div class="figure-caption">3A: Sub-caption</div>
        </div>
        <div>
            <div class="figure-frame" data-fig="fig3b">
                <img src="assets/img/panels/fig3b.png" alt="Description">
            </div>
            <div class="figure-caption">3B: Sub-caption</div>
        </div>
    </div>
    <aside class="notes">Speaker notes here.</aside>
</section>

Two-column text + figure slide (most common layout):

<section>
    <h2>Slide Title</h2>
    <div class="two-col-layout">
        <div class="col-text" style="font-size: 0.8em;">
            <ul>
                <li><strong>Point 1:</strong> Explanation</li>
                <li><strong>Point 2:</strong> Explanation</li>
            </ul>
        </div>
        <div class="col-img">
            <div class="figure-frame" data-fig="fig2a">
                <img src="assets/img/panels/fig2a.png" alt="Description">
            </div>
            <div class="figure-caption">Figure 2A: Caption</div>
        </div>
    </div>
    <aside class="notes">Speaker notes.</aside>
</section>

Math/equation slide (uses MathJax3 plugin):

<section>
    <h2>Slide Title</h2>
    <div class="math-block">
        $$
        \Delta G = -RT \ln K
        $$
    </div>
    <ul style="font-size: 0.78em; line-height: 1.7;">
        <li><strong>\(\Delta G\):</strong> Free energy change</li>
    </ul>
    <aside class="notes">Walk through the equation step by step.</aside>
</section>

Plain-English framing cards — for section openers and proposal-style aims. Use these to lead with the "why", then state hypothesis, what the section enables, and limitations.

<section class="section-slide aim-1-section">
    <h1><span class="aim-number aim1-text">Aim 1:</span> Short aim title</h1>
    <p>Goal: plain-English reason this aim matters.</p>
    <div class="why-strip">
        <div class="why-card fragment fade-in"><div class="why-kicker">Why it matters</div><p>Clinical or scientific motivation.</p></div>
        <div class="why-card fragment fade-in"><div class="why-kicker">Hypothesis</div><p>Plain-English hypothesis.</p></div>
        <div class="why-card fragment fade-in"><div class="why-kicker">Enables</div><p>What the result unlocks.</p></div>
        <div class="why-card fragment fade-in"><div class="why-kicker">Limitation</div><p>Scope boundary.</p></div>
    </div>
    <aside class="notes">Lead with the goal; click through why, hypothesis, enables, and limitation.</aside>
</section>

Method/tradeoff cards — for algorithm menus, interpretation panels, or hypothesis-generation versus validation distinctions.

<div class="method-menu">
    <div class="method-card fragment fade-in">
        <h3>Hypotheses</h3>
        <p>Use interpretation tools to nominate candidate features.</p>
    </div>
    <div class="method-card fragment fade-in">
        <h3>Validation</h3>
        <p>Test candidates against held-out data and prespecified controls.</p>
    </div>
</div>

Feature-family pipeline card — use .feature-family-step when a pipeline step contains long badges. Badges wrap inside the card and inherit distinct feature-family colors.

<div class="pipeline-step step-1 feature-family-step">
    <div class="pipe-num">Step 1</div>
    <div class="pipe-title">Four feature families</div>
    <div class="pipe-body">
        <span class="badge physiology">Routine physiology</span>
        <span class="badge process">Routine workflow</span>
        <span class="badge mixed">Intentional measurements/interventions</span>
        <span class="badge intentional-workflow">Intentional workflow</span>
    </div>
</div>

Expected outcomes table — add expected-outcomes-table to the table and aim row classes for colored summaries.

<table class="expected-outcomes-table">
    <tbody>
        <tr class="aim1-row"><td><strong>1.</strong> Input representation</td><td>Outcome text.</td></tr>
        <tr class="aim2-row"><td><strong>2.</strong> Signal source</td><td>Outcome text.</td></tr>
        <tr class="aim3-row"><td><strong>3.</strong> Latent interventions</td><td>Outcome text.</td></tr>
    </tbody>
</table>

Section break slide:

<section class="section-slide">
    <h1>Section Title</h1>
    <p>Brief subtitle</p>
    <aside class="notes">Transition notes.</aside>
</section>

Text-only slide (takeaways, discussion):

<section>
    <h2>Key Takeaways</h2>
    <ul style="font-size: 0.78em; line-height: 1.7;">
        <li><strong>Point 1</strong> — explanation</li>
        <li><strong>Point 2</strong> — explanation</li>
    </ul>
    <aside class="notes">Speaker notes.</aside>
</section>

Hidden/backup slide (for Q&A appendix):

<section data-visibility="hidden">
    <h2>Backup: Detail Slide</h2>
    <p>This slide is hidden from navigation but can be jumped to during Q&amp;A.</p>
    <aside class="notes">Backup content for anticipated questions.</aside>
</section>

Component Classes (Already Styled in style.css)

The theme ships with ready-made component classes. Use them instead of inventing inline-styled <div>s, so the deck stays visually coherent and accessible.

Aim flow card row — for outline / expected-outcomes overviews. Three colored cards (aim-1, aim-2, aim-3) with optional aim-arrow separators.

<div class="aim-flow">
    <div class="aim-card aim-1">
        <div class="aim-num">Aim 1</div>
        <div class="aim-title">Short headline</div>
        <div class="aim-status">Status / one-liner</div>
    </div>
    <div class="aim-arrow">→</div>
    <div class="aim-card aim-2">…</div>
    <div class="aim-arrow">→</div>
    <div class="aim-card aim-3">…</div>
</div>

Three-column info row — three side-by-side colored cards for "use cases", "options", "tradeoffs". Each info-card has a colored left border.

<div class="info-row-3">
    <div class="info-card"><div class="info-title">Title</div>Body text…</div>
    <div class="info-card">…</div>
    <div class="info-card">…</div>
</div>

Critique vs counter-evidence compare grid — two opposing panels with a center arrow. compare-panel.before is amber, compare-panel.after is indigo.

<div class="compare-grid">
    <div class="compare-panel before">
        <div class="cmp-title">Critique</div>
        <ul>…</ul>
    </div>
    <div class="compare-arrow">⇋</div>
    <div class="compare-panel after">
        <div class="cmp-title">Counter-evidence</div>
        <ul>…</ul>
    </div>
</div>

Taxonomy grid — three categorical columns with distinct colors. Pre-defined modifiers physiology (emerald), process (amber), mixed (slate).

<div class="taxonomy-grid">
    <div class="taxonomy-card physiology"><div class="tax-title">Physiology</div><div class="tax-body">…</div></div>
    <div class="taxonomy-card process"><div class="tax-title">Process</div><div class="tax-body">…</div></div>
    <div class="taxonomy-card mixed"><div class="tax-title">Mixed</div><div class="tax-body">…</div></div>
</div>

Decision-criteria grid — numbered acceptance criteria as 2×2 cards with circular numbers.

<div class="criteria-grid">
    <div class="criterion">
        <span class="cri-num">1</span><span class="cri-title">Threshold</span><br>
        Body text describing the criterion.
    </div>
    <!-- repeat for criteria 2–4 -->
</div>

Inline badges — pill labels for inline aim/category tags. Modifiers: aim1/aim2/aim3, physiology/process/mixed.

<span class="badge aim2">Aim 2</span>
<span class="badge physiology">Physiology</span>

Callout — light indigo block with an accent left bar; use for the headline framing on a slide.

<div class="callout">The single thing the audience should remember from this slide.</div>

Schematic — bordered container that holds an inline <svg> diagram (pipeline, study-design flow). The CSS auto-fits the SVG to slide width.

<div class="schematic">
    <svg viewBox="0 0 1100 320" xmlns="http://www.w3.org/2000/svg">…</svg>
</div>

Per-aim color tokens — when you need a custom inline element, reach for the CSS variables instead of hex codes: var(--aim1), var(--aim2), var(--aim3), var(--physiology), var(--process), var(--mixed), var(--accent), var(--muted).

Click-by-click reveal cadence

Every bullet that the presenter wants to reveal on its own click should carry class="fragment fade-in". The matching <aside class="notes"> (and the slide's block in speaker_notes.html) should use explicit CLICK markers between segments so the speaker view tells the presenter exactly what to say between clicks:

<ul>
    <li class="fragment fade-in">First point.</li>
    <li class="fragment fade-in">Second point.</li>
    <li class="fragment fade-in">Third point.</li>
</ul>
<aside class="notes">
    Open with the framing sentence.<br>
    (Click) item 1 — read the headline number.<br>
    (Click) item 2 — extend with the specific finding.<br>
    (Click) item 3 — link back to the aim.<br>
    Transition: "this is exactly what comes next."
</aside>

Speaker Notes Guidelines

Each <aside class="notes"> block should contain:

1. What the figure shows — describe the data, axes, conditions
2. Key result — the punchline of this slide
3. Context — why this matters in the paper's narrative
4. Transition — optional lead-in to the next slide

Write notes in natural speech — as if coaching the presenter. Use concrete numbers and names.

Good example:

"This scatter plot shows CB bias scores on the x-axis versus SAXS-measured percent open conformation on the y-axis. The Spearman correlation is 0.81 — very strong. Open-biased variants cluster in the upper right, while closed-biased cluster lower left. What's remarkable is that CB uses only static backbone structures..."

Bad example (too vague):

"This figure shows the correlation is good."

Phase 5: Create Speaker Notes

Write a speaker_notes.html file using the template in resources/speaker_notes_template.html. The HTML notes page should be the primary rehearsal artifact, not a dumping ground. It should include:

• Top navigation and sidebar — direct links to the talk script, slide cards, backup slides, quick reference, Q&A, and pronunciation guide.
• Standalone talk script — complete, natural spoken prose for every slide. The presenter should be able to rehearse from this section without looking at the slides.
• Click markers — use <span class="click">CLICK</span> exactly where the matching deck fragment appears.
• Slide cards — collapsible per-slide reference cards containing what's on screen, why it matters, what to say, and deeper technical or citation details.
• Backup-slide section — Q&A-only hidden-slide material, using the same slide-card pattern.
• Quick reference card — consolidated table of key results/statistics.
• Anticipated Q&A — question blocks with direct answers and slide references.
• Pronunciation guide — names, terms, symbols, and acronyms.

Write notes in natural speech — as if coaching a nervous presenter.

---

Reference Template

Copy the CSS and JS infrastructure from the existing presentation:

mkdir -p <output>/show_ready/assets/{css,img/panels}
cp <output>/assets/css/style.css <output>/show_ready/assets/css/
cp <output>/assets/img/panels/*.png <output>/show_ready/assets/img/panels/

Use this HTML shell (found in resources/template_shell.html in this skill folder):

• Reveal.js 5.0.4 CDN
• 1280×720 (16:9 widescreen)
• RevealNotes plugin for speaker view
• MathJax3 for display and inline equations ($$...$$ and \(...\))
• Settings panel (theme, font, font scale, fig scale, transition, progress, controls)
• Custom overview (O / Esc) with main slides and hidden backup slides
• Presenter window from the Fullscreen button with current notes and next-click preview
• Editable slide text with browser autosave, reset, and "Download edited deck"
• Interactive figure controls (zoom, pan, reset, and centered lightbox)

Figure behavior in the shell:

• Single-click a figure to open a centered, enlarged lightbox.
• Click outside the enlarged figure, click the close button, or press Escape to return to the slide.
• The toolbar still supports explicit zoom, pan, reset, and expand controls.

Available font choices in the settings panel: Montserrat, Source Sans 3, Inter, Fira Sans, Lato, Open Sans, Roboto, Nunito Sans, Work Sans, IBM Plex Sans, Noto Sans, Crimson Pro, and system UI fonts.

---

Quality Checklist

Before delivering the final presentation, verify:

• Narrative flow — slides tell a coherent story from background to conclusions
• Figure selection — only the most impactful panels are used (not every panel)
• Captions — every figure has a brief, informative caption
• Speaker notes — every slide has 3+ sentences of notes
• Discussion questions — 3–5 thoughtful questions included
• Browser test — open in browser, navigate all slides, check images load
• Speaker view — press S to verify notes appear correctly
• Presenter view — use Fullscreen button; verify next-click preview and notes update
• Overview — press O or Esc; verify hidden backup slides are separated from main slides
• Edit/download — test slide edit mode, autosave, reset, and index_edited.html download
• MathJax — all equations render in the deck, presenter window, and speaker notes page
• No text overflow — bullet points and titles fit within the slide
• 16:9 aspect ratio — verify slide dimensions are 1280×720

---

Tips

• Less is more. A 20-slide curated deck is better than a 50-slide figure dump. Pick the figures that tell the story.
• One idea per slide. Don't overload slides with multiple unrelated panels.
• Two-column layout is your friend. The two-col-layout pattern (text left, figure right) is the most used layout in practice.
• Use section breaks. When transitioning between major topics (e.g., "Validation" → "Application"), use a section-slide with just a title.
• Use hidden slides for backup. Add data-visibility="hidden" to slides with extra detail — they won't show during the talk but can be jumped to during Q&A.
• Write notes for a nervous presenter. Include exact numbers, pronunciations of tricky terms, and suggested emphasis points.
• Pair structure + data. Whenever possible, show a structural figure alongside quantitative data on the same slide (using figure-row or two-col-layout).