create-presentation

Create a Slidev Presentation from an Outline

This skill teaches the agent how to turn a user's rough outline (typically in org-mode, markdown, or plain text) into a polished Slidev presentation with appropriate structure, animations, and speaker notes.

Setup (one-time, user-side)

Before this skill can produce runnable output, the user must have:

1. Node.js and npm

node --version   # should be >= 18
npm --version

If missing, install via nvm, fnm, or the system package manager.

2. (Optional but recommended) A filesystem that supports symlinks

Slidev's npm install creates symlinks in node_modules/.bin/. FUSE-based cloud filesystems (OneDrive, Google Drive, Dropbox) often don't support symlinks, causing EPERM: operation not permitted, symlink errors.

Workaround: If the slides need to live on a cloud-synced path (e.g. for backup), keep node_modules separately in /tmp/ or ~/code/ and run slidev from there, pointing at the real slides.md. Specifically:

# Set up node_modules on local filesystem
mkdir -p /tmp/slidev-runtime
cp package.json /tmp/slidev-runtime/
cd /tmp/slidev-runtime && npm install

# Run slidev from there, but the slides.md stays in the real location
cp <real-path>/slides.md /tmp/slidev-runtime/slides.md
cd /tmp/slidev-runtime && npx @slidev/cli slides.md --open

Sync the slides.md back to the real location after each edit.

Workflow

Step 1: Read and understand the outline

1. Read the entire outline file. Don't skim — understand the flow, the main message, and the intended audience.
2. Identify referenced assets: images, screenshots, links, files. Look for file:, attachment:, or ![...](...) references. Follow them and view each image.
3. Identify the audience and duration if stated (e.g., "lab meeting", "conference talk", "45 min"). If not stated, ask the user or assume ~30 min of content for a lab talk.
4. Identify the narrative arc: hook → context → main content → takeaways.

Step 2: Plan the slide structure

Create a mental (or explicit) todo list of slides before writing any markdown. For each slide, decide:

• Title (short, direct — not a full sentence)
• Layout (default, center, two-cols, image, section, cover)
• Content type (bullets, code, diagram, image, quote)
• Animation (static, v-click progressive reveal, code highlight steps)
• Speaker notes (3–8 sentences elaborating what you'd say)

Principles:

• One idea per slide.
• Prefer images/diagrams over bullet walls where appropriate.
• Animations should have purpose — use v-click to pace information, not for decoration.
• Section dividers are optional — for short talks (<20 slides), they waste slides. Drop them unless the talk has >4 clearly separate sections.

Step 3: Handle images and diagrams

For existing images (from the outline):

1. Copy them to public/ in the slidev project folder.

2. Reference with absolute paths: <img src="/image.png" />

3. For split reveal animations (showing part of an image first, then expanding), use:

   <div class="flex justify-center">
     <div class="overflow-hidden rounded shadow transition-all duration-700"
          :style="$clicks >= 1 ? 'max-width: 100%' : 'max-width: 30%'">
       <img src="/my_figure.png" style="min-width: 900px;" />
     </div>
   </div>
   <div v-click="1" class="hidden" />
   

For missing diagrams:

1. Prefer Mermaid for flowcharts, sequence diagrams, timelines, ER diagrams — just use a mermaid code block.
2. Prefer inline HTML/Tailwind for custom layouts (boxes, arrows, chains).
3. Only resort to external image generation if neither of the above fits — and ask the user first.

Example: horizontal chain diagram in pure HTML/Tailwind:

<div class="flex items-center justify-center gap-2 mt-12 text-sm">
  <div class="flex flex-col items-center">
    <div class="px-4 py-2 rounded-lg bg-gray-100 dark:bg-gray-800 font-bold">Item A</div>
    <div class="text-xs op-40 mt-1">2024</div>
  </div>
  <div class="text-gray-300 text-xl">&rarr;</div>
  <!-- ... more items ... -->
</div>

Step 4: Write the slides.md

Use the Slidev syntax:

• Frontmatter at the top sets theme, title, author, transitions.
• Slide separators are --- on their own line.
• Per-slide frontmatter goes between --- lines: layout: center, class: text-xl, etc.
• Speaker notes are HTML comments at the end of the slide: <!-- notes here -->. The "at the end" part matters — comments elsewhere are ignored.
• Progressive reveal with <v-click>...</v-click> or v-click directive on any element.
• Code highlighting animation with \``python {all|1|2-3|4-5}{lines:true}` — numbers refer to 1-indexed line numbers; pipes separate animation steps.

Step 5: Write generous speaker notes

Speaker notes should:

• Be conversational, not a repeat of the slide text.
• Include transitions between slides ("This leads us to...", "Now let's talk about...").
• Flag interactive moments (e.g., "[Wait for responses]", "[Show of hands]").
• Be at least 3 sentences per slide, often more.
• For animated slides, insert [Click] markers where each step is revealed.

Example:

# My Slide

Content here.

<!--
This is where we pivot from the problem statement to the solution. The key point to make is that naive approaches fail because of X — audience members might be tempted to suggest Y, but Y has flaw Z.

[Click to reveal the solution]

And here's where our approach comes in. Emphasize that this is NOT a new technique, but rather a clever composition of existing tools.
-->

Step 6: Set up the project

Create a minimal slidev project:

// package.json
{
  "name": "my-talk",
  "private": true,
  "scripts": {
    "dev": "slidev --open",
    "build": "slidev build",
    "export": "slidev export"
  },
  "dependencies": {
    "@slidev/cli": "^52.0.0",
    "@slidev/theme-default": "latest"
  }
}

Then:

npm install
npx @slidev/cli slides.md --open

Verify the build works (slidev build) before handing back to the user.

Step 7: Review and iterate with the user

• Start the dev server (npx @slidev/cli slides.md --open) so they can see it live. Hot reload is on by default.
• Ask for feedback after each major change.
• Common iteration requests:
  • "Drop this slide" → remove the --- to --- block
  • "Animate this image" → wrap in the overflow/max-width pattern above
  • "Add a QR code for the poll" → use an <img> or generate QR from a URL (e.g., qrserver.com or local CLI)
  • "Highlight different lines in the code block" → adjust the {all|1|2-3} pattern
  • "Show more/less at once" → adjust v-click timing

Common pitfalls

Pitfall	Fix
Speaker notes not showing in presenter mode	Notes must be at the END of the slide as an HTML comment
font-size: Xmm renders text 3.5x too large	In SVG/slidev contexts with viewBox, use px or unitless — never mm
Code highlight steps are misaligned after editing code	Recount line numbers (1-indexed) and update `{1
v-click numbering broken after adding elements	v-click indices are global per slide — adding an element shifts subsequent indices; use explicit at="N" to pin
Theme not found after npm install	@slidev/theme-default must be explicitly in dependencies
Slidev dies when backgrounded	Run inside tmux new-session -d -s slidev 'npx @slidev/cli slides.md' instead

What to include vs. leave out

Include:

• Every concrete example, dataset, or number the user mentions
• Every image referenced in the outline (copy to public/)
• Every link or file path the user wants to surface (as visible footnotes or inline)
• A takeaways/summary slide near the end
• A discussion/Q&A slide at the very end

Leave out (unless requested):

• Section divider slides for short talks (<20 slides)
• Redundant introduction slides (title slide + outline is usually enough)
• Long bulleted agendas if the talk is <15 min
• Your own opinions or embellishments that weren't in the outline

What to do if the skill fails

Symptom	Likely cause	Fix
npm install fails with EPERM: symlink	Filesystem doesn't support symlinks (OneDrive, Drive)	Install in /tmp/ and point at remote slides.md
Mermaid diagram not rendering	Unsupported diagram type or syntax error	Test in https://mermaid.live first
Images not loading	Wrong path (must be absolute from public/)	Use <img src="/foo.png" />, not ./foo.png
slidev command not found	Not installed or wrong package	Use npx @slidev/cli (not npx slidev)
Hot reload not updating	Slidev was started from cached /tmp copy	Sync your slides.md to the copy, or restart slidev

What this skill does NOT cover

• PowerPoint/Keynote presentations — use the pptx or scientific-slides skill.
• LaTeX Beamer — use the scientific-slides skill.
• Research poster design — use the venue-templates or scientific-visualization skill.
• Recording/exporting to video — Slidev has built-in recording; see https://sli.dev/guide/recording.