Presentation Generator

What This Skill Produces

Complete <name>/presentation.md files that build successfully into:

• •Interactive RevealJS HTML presentations
• •MP4 videos with TTS narration (when using full build)

roughcut uses a custom markdown format — not standard RevealJS syntax. This skill is the expert in that format.

Interactive Workflow

Follow these phases in order. Do not skip the design choices phase — it prevents rework and produces better presentations.

Phase 0: Topic Discovery

Determine what the user has:

If they provide notes/outline/content: Extract the topic, key concepts, audience, and style from their input. Proceed to Phase 1.

If they say "create a presentation about X": Research the topic first:

1. •Use WebSearch to gather current information on the topic
2. •Summarize findings into 5-8 key themes/sections
3. •Present the research summary and ask: "Does this capture what you want to cover? Anything to add or remove?"
4. •Proceed to Phase 1 with the refined research

Phase 1: Design Choices

Use AskUserQuestion to present structured choices. Ask these as a single multi-question prompt:

Question 1 — Presentation Style:

• •Tutorial — Hands-on, code-heavy, step-by-step learning
• •Overview — Conceptual, high-level explanation of a topic
• •Demo — Live walkthrough, showing tools/features in action
• •Status Update — Brief, metrics-focused, for stakeholders

Question 2 — Audience Level:

• •Beginner — No prior knowledge assumed, explain fundamentals
• •Intermediate — Familiar with basics, focus on practical application
• •Advanced — Deep technical content, assumes strong foundation

Question 3 — Theme (recommend based on content type, see Style Guide below):

• •Present 3 theme options with rationale, marking the recommended one

Question 4 — Length:

• •Quick (5-8 slides) — Lightning talk, brief overview
• •Standard (10-15 slides) — Most presentations, good depth
• •Deep Dive (15-25 slides) — Comprehensive coverage, tutorials

Phase 2: Outline Preview

Create and present the outline before generating any slides:

## Proposed Structure (N slides)

**Section 1: Introduction** (2 slides)
1. Title slide — "[Title]"
2. Overview — Hook + what we'll cover

**Section 2: [Topic]** (4 slides)
3. [Concept] — bullets + fragments
4. [Detail] — code example
5. [Visual] — @image-prompt slide
6. [Deep dive] — vertical slide group

**Section 3: [Topic]** (3 slides)
...

**Conclusion** (2 slides)
N-1. Key takeaways
N. Next steps / resources

Estimated narration: ~X minutes

Approve this structure, or tell me what to change?

Wait for user approval before generating slides.

Phase 3: Section-by-Section Generation

For each section:

1. •Generate 3-5 slides following the content rules below
2. •Self-check: verify text limits, no tables, fragments on bullets only
3. •Show to user with running tally: "Generated 8/15 slides"
4. •User approves or requests changes
5. •Continue to next section

Phase 4: Build & Deliver

After writing the complete tutorials/<name>/presentation.md file:

TUTORIAL=<name> npm run tutorial:html

This is mandatory. The user cannot view the presentation until you build it. If linting fails, read the errors, fix the markdown, and rebuild. The linter catches all syntax issues with helpful suggestions.

Once built, tell the user:

# Preview in browser
TUTORIAL=<name> npm run dev

# Test auto-advance timing
TUTORIAL=<name> npm run dev:auto

# Full build with TTS audio + video (costs API credits!)
TUTORIAL=<name> npm run tutorial:full

Theme & Style Guide

Theme Recommendations by Content Type

All 12 valid themes: black, white, league, beige, sky, night, serif, simple, solarized, blood, moon, dracula

Background Gradient Palette

Use these curated gradients for visual variety between sections:

• •Title/Hero: linear-gradient(135deg, #667eea 0%, #764ba2 100%) — blue-purple, professional
• •Introduction: linear-gradient(135deg, #2E3192 0%, #1BFFFF 100%) — deep blue-cyan, inviting
• •Success/Conclusion: linear-gradient(135deg, #11998e 0%, #38ef7d 100%) — green, achievement
• •Warning/Important: linear-gradient(135deg, #f093fb 0%, #f5576c 100%) — pink-red, attention
• •Calm/Neutral: linear-gradient(135deg, #a18cd1 0%, #fbc2eb 100%) — lavender-pink, soft
• •Dark accent: #1a1a2e — near-black with blue tint, good for code sections

Transition Strategy — The 70-20-10 Rule

Apply transitions with discipline, not variety:

• •70% fade — All content slides (default, smooth, professional)
• •20% convex — Section dividers only (visual separation between major sections)
• •10% zoom — Title slide and final slide only (bookends the presentation)

Never use slide or concave in generated presentations — they add visual chaos without value. Never specify a different transition on every slide.

Design System Principles

Consistent visual rhythm makes a presentation feel professional:

• •Color palette: Pick 3 colors from the topic/brand and use them everywhere. Don't introduce new colors mid-presentation.
• •Background rhythm: Alternate solid backgrounds (content slides) with gradients (section dividers). This creates predictable visual "chapters."
• •Never put gradients on content-heavy slides — gradients are for titles, section breaks, and conclusion. Code, bullets, and diagrams go on solid backgrounds.
• •center: false is almost never correct — RevealJS defaults to centered content for good reason. Only override this if you have a specific layout need.

Readability on Gradient Backgrounds

Gradient slides must have high-contrast text:

• •Always use white text on medium-to-dark gradients
• •Keep text minimal — short title + optional subtitle, not bullet lists
• •Never put code blocks on gradient backgrounds
• •The custom CSS should include this rule (generated templates already do):
  css

  .reveal section[data-background-gradient] h1,
  .reveal section[data-background-gradient] h2,
  .reveal section[data-background-gradient] p,
  .reveal section[data-background-gradient] strong,
  .reveal section[data-background-gradient] em {
    color: #ffffff !important;
  }
  

Custom Markdown Format Essentials

Required Frontmatter

---
title: "Presentation Title"    # REQUIRED
theme: dracula                 # REQUIRED (one of 12 themes)
preset: manual-presentation    # Recommended for iteration
voice: adam                    # Optional: ElevenLabs voice
resolution: 1920x1080         # Optional: video resolution
config:                        # Optional: RevealJS overrides
  controls: true
  progress: true
customCSS: ./styles/custom.css # Optional: external CSS file
---

Styling options:

• •customCSS: ./styles/custom.css — External CSS file (recommended for larger stylesheets)
• •customStyles: | — Inline CSS in YAML pipe syntax (fine for small overrides, 1-5 rules)

Key Directives (Most Used)

Slides are separated by --- on its own line.

@audio: — Narration text (multi-line format recommended for caching)

@audio: First sentence establishes context.
@audio: Second sentence adds detail.
@audio: Third sentence wraps up. [1s] With a pause.

@fragment — Progressive reveal (ONLY on bullet lists, never numbered lists)

- First point @fragment
- Second point @fragment +1s
- Third point @fragment +2s

@transition: — Slide transition: none, fade, slide, convex, concave, zoom

@background: — Color, gradient, or image path

@background: linear-gradient(135deg, #667eea 0%, #764ba2 100%)

@image-prompt: — AI image generation prompt (be specific about style, mood, composition)

@vertical-slide: — Create sub-slides navigated with DOWN arrow

@duration: / @pause-after: — Timing control (format: 5s or 1500ms)

@notes: — Speaker notes (press 'S' to view)

For the complete reference of all 21 directives, read docs/FEATURES.md. For linting rules and error formats, read docs/LINTING_SPEC.md.

Content Rules

Apply these to EVERY slide. Check before showing to user.

Text Limits

• •Slide title: 3-5 words ideal, 8 words absolute max
• •Bullet point: 5-8 words ideal, 10 words absolute max
• •Bullets per slide: 3-4 ideal, 5 absolute max
• •Body text: 1-2 sentences ideal, 3 absolute max

Forbidden Elements

• •NO TABLES — Tables render poorly in RevealJS. Convert to bullet lists or split across slides.
• •NO LONG HEADERS — Keep to 3-5 words
• •NO DENSE PARAGRAPHS — Use bullets or split into multiple slides

One Idea Per Slide

If a slide feels crowded, split it. 20 clear slides > 10 cramped ones.

Audio Narration Pattern

2-4 sentences per slide, multi-line format:

@audio: Opening sentence establishes context.
@audio: Detail sentence provides key information.
@audio: Closing sentence transitions or reinforces.

Timing guideline: 8-12 seconds per slide. Match fragment timing to narration flow.

Code Samples

• •Keep under 15 lines per slide
• •Include explanatory comments
• •Use realistic variable names
• •Match the topic's language/framework
• •Split long examples across multiple slides

Asset Placeholders

• •Use @image-prompt: for conceptual/visual slides (be specific about style and mood)
• •Use <!-- TODO: Add screenshot of X --> for user-provided screenshots
• •Use @notes: to suggest diagrams the user could create

Common Mistakes

These are the top issues that cause linting failures:

1. •Fragments on numbered lists — 1. Item @fragment fails. Use - Item @fragment instead.
2. •Invalid duration format — 5 seconds fails. Use 5s or 1500ms.
3. •Invalid theme name — dark fails. Use black. Check the 12 valid options.
4. •Pause markers outside @audio — Text [1s] here fails. Pause markers only work inside @audio: lines.
5. •Missing required frontmatter — Both title and theme are required.

The linter catches all of these with helpful error messages and typo suggestions. Run the build and read the output.

Design Anti-Patterns

Avoid these patterns that make presentations look unprofessional:

1. •Transition soup — Every slide uses a different transition. Apply the 70-20-10 rule instead.
2. •Gradient overload — More than 30% of slides have gradient backgrounds. Gradients are for section breaks, not content.
3. •Dark text on dark gradient — Always ensure white text on gradient backgrounds via CSS.
4. •center: false without explicit reason — This pushes content to the top-left. RevealJS centering is correct for nearly all presentations.
5. •Feature showcase syndrome — Using every directive on every slide to "demonstrate" capabilities. A good presentation is invisible — the audience notices the content, not the effects.
6. •Inconsistent backgrounds with no rhythm — Random alternation of colors. Use a consistent pattern: solid for content, gradient for dividers.

Templates

Use these as starting points — copy structure and adapt to the user's topic:

• •assets/template-minimal.md — 5 slides, basic structure
• •assets/template-comprehensive.md — 11 slides, demonstrates most directives
• •assets/template-tutorial.md — 15 slides, code-heavy instructional format

File Naming

When creating presentations:

• •Derive the directory name from the title: lowercase, hyphenated
• •Example: "Docker Basics for Developers" → tutorials/docker-basics/presentation.md
• •Always write to tutorials/<name>/presentation.md