Beamer Deck Skill

Generate academic Beamer presentations with original themes, rhetoric-driven structure, and multi-agent review. Internalises Scott Cunningham's rhetoric framework and implements an adversarial review workflow.

Purpose

Create polished, zero-warning Beamer decks for academic contexts: seminars, conference talks, teaching lectures, and working decks for coauthors. Every deck gets a custom theme, assertion-driven titles, and parallel review by rhetoric and graphics sub-agents.

NOT for project status updates — use project-deck for those.

When to Use

Academic seminar presentations
Conference talks (15–45 min)
Teaching lectures (undergraduate or PhD)
Working decks for coauthors or supervisors
Any presentation that needs rhetoric discipline and visual quality

Critical Rules

Build artifacts go to out/, PDF stays in the source directory. Create .latexmkrc with $out_dir = 'out' and an END {} block to copy the PDF back if missing. Use latex for compilation — it handles error resolution automatically. See latex for manual config details.
Python: Always use uv run python. Never bare python, python3, pip, or pip3.
Fix ALL warnings. Overfull hbox, underfull hbox, overfull vbox, underfull vbox — no matter how small. Parse the .log file. Recompile until clean.
Titles are assertions, not labels. "Distance increases abortion rates" — not "Results". Every frame title states a claim.
One idea per slide. Not a guideline. A law. If a slide has two ideas, split it.
Use the unified template. Always use \usepackage[<institution>]{user-beamer} from templates/beamer/. Options: preset-a, preset-b, preset-c, preset-d, plain. Never use default Beamer themes (Warsaw, Madrid, etc.) as-is, and never create one-off preambles. See [templates/beamer/README.md] for available custom commands and how to add institutions.
Code-first figures. Generate figures via R or Python scripts before inserting. Never use placeholder images. Always save the script alongside the figures — never generate a figure without preserving the code that created it.
If a .bib file is used, validate it. Cross-reference all \cite{} keys against the bibliography file. See bib-validate for the full protocol.
Never define parameterized TikZ styles inside a frame. # inside a Beamer frame body is consumed by the frame parser before TikZ sees it, producing Illegal parameter number errors that cascade and resist all downstream fixes. Define ALL \tikzset{...} and .style={..., #1} entries in the preamble; use them inside frames. See ../shared/tikz-rules.md Rule 11.

Rhetoric Principles

Full framework (Three Laws, MB/MC, Aristotelian Triad, Narrative Arc, Pyramid Principle, Devil's Advocate): ../shared/rhetoric-principles.md

Scott's original essay: resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md

Quality Scoring

Apply numeric quality scoring using the shared framework and skill-specific rubric:

Framework: ../shared/quality-scoring.md — severity tiers, thresholds, verdict rules
Rubric: references/quality-rubric.md — issue-to-deduction mappings for this skill

Start at 100, deduct per issue found, apply verdict. Compute the score in Phase 7 and report it in the final output.

Context-Specific Guidance

See ../shared/rhetoric-principles.md for the full Aristotelian Triad framework. Context-specific Ethos/Pathos/Logos balance and adjustments are applied in Phase 2 based on audience type (academic seminar, conference talk, teaching lecture, working deck).

Workflow: 7 Phases

You (orchestrator)
├── Phase 1: Gather context        (direct)
├── Phase 2: Design structure       (direct)
├── Phase 3: Build deck             (direct)
├── Phase 4: Fix all warnings       (direct)
├── Phase 5: Rhetoric review        (sub-agent — Explore)
├── Phase 6: Graphics review        (sub-agent — Explore)  ← parallel with Phase 5
└── Phase 7: Apply & finalise       (direct)

Phase 1: Gather Context (Direct)

Read project files, content sources, and audience brief. Ask the user clarifying questions:

Audience: Who is this for? (seminar, conference, teaching, coauthors)
Duration: How long is the talk?
Content source: Paper draft? Notes? Existing slides? Code output?
Special requirements: Specific figures, institutional branding, language?

Check for existing .bib files in the project. If citations are needed, note this for Phase 3.

Phase 2: Design Structure (Direct)

Choose rhetoric balance based on audience (see table above)
Outline slide sequence with assertion titles — write each title as a claim
Plan narrative arc — consult docs/reference/talk-design.md for format-specific arcs (empirical, structural, theory, descriptive) and audience calibration
Choose institution option for user-beamer — colours and fonts are set by the template
Identify figures needed — which need to be generated via code?

Present the outline to the user for approval before building.

Phase 3: Build Deck (Direct)

Generate figures first — run R/Python scripts, save to figures/
Write .tex file using the unified template: \documentclass[aspectratio=169,11pt]{beamer} + \usepackage[university]{user-beamer} (or other institution option). Use \fbinstitute and \fbemail for metadata. Custom commands: \contribcard, \phasecircle, \accentbox, \highlightbox, standoutframe environment.
Use 16:9 aspect ratio (already in the documentclass above)
Create .latexmkrc if not present ($out_dir = 'out' + END {} block to copy PDF back)
Compile using latex — this handles missing packages, font conflicts, citation key mismatches, and stale cache automatically
If using citations: add \addbibresource{references.bib} or \bibliography{} as appropriate

Phase 4: Fix All Warnings (Direct)

After latex resolves errors, address remaining warnings (which autofix does not fix):

Parse out/*.log for overfull/underfull hbox/vbox warnings
Fix every single one — adjust text, resize figures, tweak \parbox, etc.
Recompile
Repeat until the log is clean

Circuit breaker — do not spiral. If the same compile error persists after 3 different fix attempts, STOP. Do not try a fourth approach. Instead:

Stop editing the .tex file.
Quote the exact error line from the .log.
List the 3 approaches tried and why each failed.
Ask the user how to proceed.

What counts as "the same error": any error that persists at the same line family after a fix (e.g., Illegal parameter number moving from line 568 to 572 is still the same error — that is the diagnostic signature in tikz-rules.md Rule 11). A fresh Overfull on a different slide after fixing the first is a new error — reset the counter.

The cost of stopping is 2 minutes; the cost of spiraling is an hour of edits that progressively obscure the original cause. This rule overrides "recompile until clean" — zero tolerance for warnings does not mean infinite attempts on the same fix.

"Compilation success does not mean visual success." Also check for silent visual errors:

TikZ: shape constraints forcing label misplacement, coordinate misalignment. If the deck contains TikZ diagrams, run the 6-pass verification from ../shared/tikz-rules.md — compute Bezier depths, check gaps, verify label fit, check shape boundary clearance.
matplotlib/ggplot: axis labels cut off, legend obscuring data, text sizing. If figures use curved arrows (arc3), compute Bézier positions using the helper functions in ../shared/tikz-rules.md § Matplotlib Extension — never guess where curves pass. Check label-to-shape clearance (Boundary Rule) and use anchor-based centering for text pairs.
PDF visual inspection: Run uv run python scripts/pdf-to-images.py <deck>.pdf to convert pages to images, then inspect each image for text overflow, element overlap, font readability, and alignment issues that are invisible in the log

Phase 5: Rhetoric Review (Sub-Agent — Explore)

Launch a sub-agent to review the .tex file against 7 criteria: narrative arc, MB/MC balance, title quality, one-idea-per-slide, transitions, Aristotelian balance, and pyramid principle.

Full prompt template: references/review-prompts.md § Rhetoric Review

Phase 6: Graphics Review (Sub-Agent — Explore)

Launch in parallel with Phase 5. Reviews TikZ diagrams, figure sizing, table formatting, colour consistency, typography, and numerical accuracy.

Full prompt template: references/review-prompts.md § Graphics Review

Phase 7: Apply and Finalise (Direct)

Read both reviewer reports
Incorporate feedback — prioritise Critical and Needs Work items
Recompile
Verify zero warnings in the log
If using a .bib file: validate all \cite{} keys resolve correctly (check log for Citation .* undefined). See bib-validate for the full cross-referencing protocol.
If significant changes were made, loop back to Phase 5 for another review round
Compute quality score — read references/quality-rubric.md, log all issues from Phases 4-6, compute score and verdict
Confirm final PDF is in the source directory (copied from out/ by .latexmkrc)

Reference Palettes

Three starting palettes (Professional, Energetic, Academic) in both LaTeX and CSS formats: ../shared/palettes.md

Use as inspiration — always create an original palette for each deck.

Output Checklist

A completed deck directory should contain:

project/
├── deck.tex              # Main Beamer file (uses user-beamer.sty)
├── deck.pdf              # Compiled PDF (copied from out/ by .latexmkrc)
├── .latexmkrc            # Output directory config
├── out/                  # Build artifacts only
├── figures/              # Generated figures (if any)
│   ├── figure_1.png
│   └── ...
├── scripts/              # R/Python scripts that generated figures (if any)
│   ├── figure_1.R
│   └── ...
└── references.bib        # Bibliography (if citations used)

[ ] PDF compiles with zero warnings
[ ] All frame titles are assertions
[ ] One idea per slide
[ ] Narrative arc: Problem → Investigation → Resolution
[ ] Rhetoric review completed (Phase 5)
[ ] Graphics review completed (Phase 6)
[ ] If .bib used: all \cite{} keys validated (see bib-validate)
[ ] Quality score computed and reported

Cross-References

| Skill | When to use instead/alongside | |-------|-------------------------------| | project-deck | For project status updates (supervisor meetings, coauthor handoffs) | | latex | Default compiler — used in Phase 3 for error resolution and citation audit | | latex | For manual compilation config details, .latexmkrc setup, engine selection | | proofread | For post-hoc review of text quality in the deck | | bib-validate | For thorough bibliography cross-referencing when citations are used | | literature | For finding and verifying citations to include | | quarto-deck | For HTML presentations (teaching, informal talks) instead of PDF | | quarto-course | For full course websites with multiple lectures, exercises, and navigation |

Scott's full rhetoric essay: resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md Scott's deck generation prompt: resources/academics/scott-cunningham/MixtapeTools/presentations/create_deck_prompt.md Scott's example decks: resources/academics/scott-cunningham/MixtapeTools/presentations/examples/