Reveal.js Deck Skill

Generate HTML presentations from Markdown using reveal-md. Applies the same rhetoric framework as /beamer-deck but outputs browser-native slides ideal for teaching, informal talks, and web sharing.

Purpose

Create polished Reveal.js presentations from Markdown files. Every deck gets assertion-driven titles, narrative arc, and rhetoric review. Output is an HTML presentation that runs in any browser — no LaTeX needed.

Use this for: Teaching, informal research talks, web-shareable presentations, interactive demos. Use /beamer-deck for: Conference talks, formal seminars, supervisor meetings, anything that needs PDF-native output.

When to Use

Teaching lectures (undergraduate or PhD) — interactive, live in browser
Informal research presentations or lab meetings
Talks where you want to share a URL instead of a PDF
Presentations with live code demos or embedded content
Quick decks where LaTeX overhead isn't justified

Python: Always use uv run python. Never bare python, python3, pip, or pip3.

Prerequisites

reveal-md (installed globally): npm install -g reveal-md
Node.js 18+ (via nvm)

Critical Rules

Python: ALWAYS use uv run python or uv pip install. Never use bare python, python3, pip, or pip3. Include this instruction in any sub-agent prompts that may run Python.
One Markdown file = one presentation. All slides live in a single .md file with --- separators.
Titles are assertions, not labels. "Distance increases abortion rates" — not "Results". Every slide title states a claim.
One idea per slide. Not a guideline. A law. If a slide has two ideas, split it.
Speaker notes use the Note: keyword. Place after slide content, before the next ---.
Custom CSS goes in a separate file. Never inline styles in the Markdown.
Figures first, slides second. Generate figures via R or Python scripts before referencing them.
Test in browser before finalising. Run reveal-md <file>.md and check every slide.

Rhetoric Principles

Same framework as /beamer-deck. Full reference (Three Laws, MB/MC, Aristotelian Triad, Narrative Arc, Pyramid Principle, Devil's Advocate, audience-specific guidance): ../shared/rhetoric-principles.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 6 and report it in the final output.

Reveal.js Markdown Format

Full format reference with basic structure, vertical slides, fragments, custom themes, and CSS examples: references/markdown-format.md

Reference palettes (Professional, Energetic, Academic) with both LaTeX and CSS variants: ../shared/palettes.md

Workflow: 6 Phases

You (orchestrator)
├── Phase 1: Gather context        (direct)
├── Phase 2: Design structure       (direct)
├── Phase 3: Build deck             (direct)
├── Phase 4: Preview & fix          (direct)
├── Phase 5: Rhetoric review        (sub-agent — Explore)
└── Phase 6: Apply & finalise       (direct)

Phase 1: Gather Context (Direct)

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

Audience: Teaching? Lab meeting? Informal talk?
Duration: How long?
Content source: Paper draft? Notes? Existing slides?
Special requirements: Code demos? Interactive elements? Specific theme?
Export needs: Browser only, or also need static HTML/PDF?

Phase 2: Design Structure (Direct)

Choose rhetoric balance based on audience
Outline slide sequence with assertion titles
Plan narrative arc — identify Act I/II/III transitions
Choose colour palette — create custom.css
Identify figures needed — which need code generation?

Present outline to the user for approval.

Phase 3: Build Deck (Direct)

Generate figures first — R/Python scripts, save to figures/
Write the .md file with YAML frontmatter and slide content
Write custom.css if custom theming is needed
Test locally: reveal-md deck.md
Add speaker notes using Note: blocks

Phase 4: Preview and Fix (Direct)

Run reveal-md deck.md to preview in browser
Check every slide for:
- Text overflow or cramped content
- Figure sizing and alignment
- Math rendering (MathJax)
- Code highlighting
- Transitions between slides
Fix issues and re-preview

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

Launch the same rhetoric review as /beamer-deck, adapted for Markdown:

subagent_type: Explore
prompt: |
  You are a rhetoric reviewer for an academic Reveal.js presentation.

  Read the file at: [PATH TO .md FILE]

  Evaluate against these criteria:

  ## 1. Narrative Arc
  - Three-act structure (Problem → Investigation → Resolution)?
  - Opening: provocative question, statistic, or bold claim?
  - Closing: single memorable takeaway?

  ## 2. MB/MC Balance
  - Cognitive load distributed smoothly?
  - Overloaded or underloaded slides?

  ## 3. Title Quality
  - Every title an assertion (a claim), not a label?

  ## 4. One Idea Per Slide
  - Any slide trying to convey multiple ideas?

  ## 5. Transitions
  - Are transitions between slides explicit?
  - Does the audience know where they are in the argument?

  ## 6. Pyramid Principle
  - Conclusions before support?

  Return structured markdown with ratings and specific slide suggestions.

Phase 6: Apply and Finalise (Direct)

Incorporate rhetoric review feedback
Re-preview in browser
Compute quality score — read references/quality-rubric.md, log all issues from Phases 4-5, compute score and verdict
Export if needed:
- Static HTML: reveal-md deck.md --static _site
- PDF: reveal-md deck.md --print deck.pdf
Confirm all files are in place

Commands Reference

Command	What it does
`reveal-md deck.md`	Live preview with hot reload (default port 1948)
`reveal-md deck.md --css custom.css`	Preview with custom CSS
`reveal-md deck.md --static _site`	Export to static HTML (shareable folder)
`reveal-md deck.md --print deck.pdf`	Export to PDF (uses Puppeteer)
`reveal-md deck.md --port 3000`	Preview on custom port
`reveal-md deck.md --theme moon`	Use built-in theme (moon, night, serif, etc.)

Press s during preview to open speaker notes view. Press f for fullscreen. Press o for slide overview.

Output Checklist

A completed deck directory should contain:

project/
├── deck.md               # Markdown presentation
├── custom.css             # Custom theme (if used)
├── figures/               # Generated figures (if any)
│   ├── figure_1.png
│   └── ...
├── scripts/               # R/Python scripts for figures (if any)
│   ├── figure_1.R
│   └── ...
├── _site/                 # Static HTML export (if generated)
└── deck.pdf               # PDF export (if generated)

All slide titles are assertions
One idea per slide
Narrative arc: Problem → Investigation → Resolution
Rhetoric review completed (Phase 5)
Speaker notes present for key slides
Math renders correctly (if used)
Tested in browser — no overflow or layout issues
Quality score computed and reported

Cross-References

Skill	When to use instead/alongside
`/beamer-deck`	For formal academic presentations (conferences, seminars) that need PDF-native output
`/project-deck`	For project status updates (supervisor meetings, coauthor handoffs)
`/proofread`	For post-hoc review of text quality
`/literature`	For finding and verifying citations to include
`/quarto-course`	For full course websites with multiple lectures, exercises, and navigation

quarto-deck