| name | slidev-build-slidedeck |
| description | Builds a complete Slidev slide deck Markdown file from the user’s notes, docs, or web links. Use when the user says things like “turn these notes into a Slidev deck”, “make slides from this doc”, “create a conference talk deck”, “draft a workshop slidedeck”, “convert this outline into Slidev markdown”, or “use these links as sources and write the slides”. Do NOT use for general writing tasks that are not a Slidev deck. |
| license | MIT |
| compatibility | Works in repositories that use Slidev (Markdown-based decks). If sources are web links, requires network access to read them. For validation, requires Node and the repo’s existing build scripts. |
| metadata | {"author":"Cursor Agent","version":"1.0.0"} |
Slidev Build Slidedeck
Instructions
Step 1: Identify the deck’s intent and constraints
Decide what the deck must achieve and the boundaries it must respect.
- Extract or infer:
- Audience (who it’s for)
- Outcome (what they should know/do after)
- Tone (e.g., conference talk, internal training, product update, workshop)
- Length target (slide count and/or minutes)
- Delivery style (talk vs workshop vs read-along)
- Hard constraints (required sections, required messages, must-include links, forbidden content)
- If the user provided a repo/theme context, prefer its existing layouts/components and writing style.
Done when: You can state the deck’s “one sentence promise” and you know the target length, tone, and constraints.
Step 2: Collect and distill source material (notes, docs, links)
Turn messy inputs into a structured content backbone.
- If the user provided links, read them and capture:
- 3–7 key claims (with short supporting details)
- Numbers/stats that deserve “fact” slides
- Examples/demos worth showing (code, screenshots, flows)
- Quotes worth pulling verbatim
- If the user provided text notes, normalize them into:
- a “source material summary” section (bulleted)
- a list of must-include artifacts (code blocks, diagrams, checklists, tables)
Done when: You have a compact source summary that can drive slide decisions without re-reading everything.
Step 3: Design the talk structure (narrative arc)
Create a section-level outline that controls pacing and attention.
Use an explicit arc appropriate to the content, for example:
- Hook → Context → Deep dive / Demos → Implications → Defense / Solutions → Takeaways → Resources → Q&A/End
For each section, define:
- Goal (why this section exists)
- Slide range budget (e.g., Slides 1–5)
- What the audience should remember
Done when: You have 4–7 named sections with goals and rough slide ranges that sum to the target length.
Step 4: Expand into a slide-by-slide blueprint (numbered)
Write a concrete plan that is easy to execute and hard to derail.
For each slide, specify:
- # (explicit numbering)
- Layout (e.g.,
cover, intro, section, default, fact, quote, center, two-cols)
- Title
- Content instructions (what must appear on the slide)
- Presenter notes intent (what the speaker says, timing cue, or the key beat)
Prefer the pattern:
- Section divider slides (
layout: section) to reset attention
- Fact/stat slides (
layout: fact) when you have a single strong number
- Demo/flow slides that show a step sequence (often best as a diagram + bullets)
- Quote slides for a single punchline / authoritative guidance
Done when: Every slide has a purpose, layout choice, and enough instruction that you can write it without inventing new structure mid-way.
Slide content style guide (MUST follow)
These rules govern how content appears on every slide. Violating them produces cluttered, article-like slides that no speaker wants to present.
Less is more — ruthlessly cut text
- A slide is NOT an article paragraph. If you can say it out loud, it belongs in presenter notes, not on the slide.
- Maximum 2-4 short bullet points per slide, or one key visual/code block. Never both a wall of bullets AND a component grid.
- Each bullet should be a punchy phrase, not a full sentence. Cut every word that doesn't earn its place.
- If a slide has more than ~40 words of visible text (excluding code blocks), it's too dense. Split it.
Spread ideas across multiple slides
- One idea per slide. If you're tempted to put two concepts on one slide, make two slides instead.
- Build a message across a sequence: slide 1 poses the question, slide 2 delivers the reveal, slide 3 adds the "so what." The speaker's voice connects them — the slides don't need to repeat each other.
- Use
layout: center for single-line reveals and dramatic moments. Let the audience read one thing and listen to you explain it.
Don't repeat yourself
- If a title or concept appeared on the previous slide, don't restate it. Move forward.
- Subtitles and body text should add new information, not rephrase the title.
Be punchy and fun
- Prefer surprising, playful, or provocative framing over dry descriptions.
- Rhetorical questions, strikethroughs for comedic effect, single-word reveals — these are your tools.
- The title alone should make someone curious. "What Do You Call Software That..." beats "OpenClaw Architecture Overview."
Titles must carry context for latecomers
- Someone glancing at the slide mid-talk should immediately understand the topic. A generic title like "Same Playbook" means nothing on its own — "Same npm Malware Playbook" anchors the audience to the subject even if they just looked up from their phone.
- Every title should answer: "If someone walked in right now, would this title tell them what we're discussing?"
Let the speaker talk
- The slide provides the visual anchor. The presenter notes provide the full narrative.
- If you find yourself writing a paragraph on a slide, move 80% of it to presenter notes and leave only the hook on the slide.
Bad vs Good examples
Bad (overloaded, article-style):
# Meet OpenClaw: "Everything Siri Was Supposed to Be"
An open-source AI assistant that lives on your machine. It connects to
WhatsApp, Telegram, Slack. It reads your emails, manages your calendar,
executes shell commands, controls your browser, and **remembers everything**.
- **Gateway** — Central orchestration (WebSocket + HTTP)
- **Skills** — Modular capabilities from ClawHub registry
- **Channels** — WhatsApp, Slack, Telegram, Discord bridges
- **Tools** — Shell, filesystem, browser, APIs
- Full shell access to your machine
- Read/write to all your files
- Send messages on your behalf
- Access environment variables & credentials
- Persistent memory across sessions
Good (split across 3 slides, concise, builds tension):
# What Do You Call Software That...
- Accepts instructions via **Telegram**
- Has **full control and access** to your machine
Then a reveal slide:
# ~~A Trojan~~ OpenClaw
Then the implications:
# OpenClaw
Open-source AI assistant that uses **Skills** from a public registry
<FeatureCard icon="💀" title="One Bad Skill"
description="Total control over the agent and everything it touches." />
Decompose lists into slide sequences
When you have a list of N related items (3 threat categories, 4 steps, 5 principles), do NOT dump them into one bullet-point slide. Instead, decompose into a sequence:
- Overview slide — show the list as a visual summary (numbered cards, a simple grid). No details, just labels. This sets up "here are N things, let me walk you through each."
- One slide per item — each gets its own centered slide with a breadcrumb (e.g. "Lethal Trifecta — 1 of 3"), a title, a short subtitle, and empty space for a visual or screenshot. The speaker notes carry the full explanation.
- Synthesis slide (optional) — a punchline that ties them together after the walkthrough.
Bad (everything on one slide):
# The Lethal Trifecta
- **Access to private data** — credentials, emails, files, API keys, environment variables — all in the agent's reach
- **Exposure to untrusted content** — emails, web pages, chat messages, documents — all flow through the agent's context window
- **Ability to communicate externally** — send emails, post to webhooks, make API calls, compose messages on your behalf
Now add persistent memory and shell access — compromised agents become persistent insider threats.
Good (overview + 3 deep-dive slides):
<!-- Overview: visual summary with numbered cards -->
# The Lethal Trifecta
[1: Private data] [2: Untrusted content] [3: External comms]
Then one slide per item:
<!-- Breadcrumb keeps the audience oriented -->
Lethal Trifecta — 1 of 3
# Access to Private Data
Credentials, emails, files, API keys — all in the agent's reach
<!-- space for screenshot or visual below -->
Then the synthesis:
Now add **persistent memory** and **shell access**
Compromised agents become persistent insider threats
This pattern works for any enumerated concept: attack stages, architecture layers, defense strategies, research findings. The number in the breadcrumb gives the audience a progress indicator and the speaker room to tell each story fully.
Step 5: Generate the Slidev Markdown deck
Create or rewrite the target .md deck file (commonly example.md) so it matches the blueprint.
Apply the slide content style guide from Step 4 to every slide.
-
Headmatter (first --- block) must include:
title, theme choice, and any repo-required configlayout for slide 1 if slide 1 is not the default (do not create a second frontmatter block just to make a cover slide)
-
For each slide:
- Use
--- slide separators
- Set per-slide
layout: frontmatter when needed
- Include the slide’s visible content
- Add presenter notes as HTML comments
<!-- ... -->
-
Choose the most legible representation for the content:
- Code blocks with selective highlighting for “read it out loud” moments
- Mermaid diagrams for flows/architectures
- Tables only when comparisons matter more than storytelling
- Progressive disclosure (
v-click / v-clicks) when the slide should be spoken line-by-line
-
After writing each slide, check: Could this be split into two simpler slides? Is there text here that should be in presenter notes instead? If the slide has both a paragraph AND a component grid, it is too much -- pick one.
Done when: The deck file exists and contains all slides from the blueprint in order, including notes. Every slide passes the "squint test" -- if you squint at it, you should see structure and whitespace, not a wall of text.
Step 6: Verify and iterate until it builds and reads well
Close the loop with a concrete “works end-to-end” check, then refine.
- Validate:
- The deck builds with the repo’s build command (or at least runs in dev)
- No broken layouts/components
- Pacing works: the hook is immediate, sections feel balanced, and takeaways are explicit
- Presenter notes exist for every slide that needs speaking guidance
- If build fails or a slide reads weak:
- Fix the smallest unit (one slide at a time)
- Re-run the build/dev check
- Repeat until done
Done when: Build/dev succeeds and the deck’s story matches the arc + slide blueprint.
Examples
User says: "Turn these rough notes into a 25-minute conference talk deck in Slidev. Use these three blog posts as sources."
Actions:
- Identify audience, outcome, tone, and slide budget (~25–35 slides).
- Read the links and extract key claims, stats, demo candidates, and quotes.
- Propose a narrative arc with 5–7 sections and slide ranges.
- Produce a numbered slide blueprint with chosen layouts (
cover, section, fact, default, quote).
- Write the Slidev
.md deck with presenter notes on every slide.
- Build/preview, then iterate on any broken slide or weak pacing until it works.
Result: A complete, buildable Slidev markdown deck with a coherent narrative and speaker notes.
User says: "Make a workshop slidedeck from our internal doc. It should be hands-on with exercises."
Actions:
- Extract constraints (hands-on, exercise cadence, timebox).
- Distill the doc into modules and exercise checkpoints.
- Create a structure that alternates concept → demo → exercise → debrief.
- Draft slides with explicit exercise instructions and expected outputs.
- Add presenter notes for facilitation cues and timing.
- Verify the deck runs and the exercises are unambiguous, then refine.
Result: A workshop deck optimized for facilitation, with clear exercises and timing notes.
User says: "Convert this outline into slides and make it look good in our theme."
Actions:
- Infer the intended narrative arc from the outline.
- Convert each outline node into a slide blueprint with layouts chosen for emphasis.
- Use the repo’s existing layouts/components and typography patterns.
- Generate the Slidev markdown and verify it renders correctly.
Result: A theme-consistent Slidev deck that matches the outline but reads like a real talk.
User says: "Here are 10 links—make a deck that summarizes them and ends with practical recommendations."
Actions:
- Read and summarize each link into 1–2 bullets, then cluster into themes.
- Create sections: context, theme clusters, synthesis, recommendations, resources.
- Use
fact slides for standout stats and quote slides for key pull-quotes.
- Produce the Slidev deck with a final checklist/recommendations section.
- Verify build/dev, iterate until it’s concise and coherent.
Result: A synthesized Slidev deck with clear recommendations and traceable source-derived content.
Troubleshooting
Error: The first slide is blank or the cover appears as slide 2.
Cause: The deck headmatter (first --- block) is always slide 1; a second --- layout: cover --- block created an extra slide.
Solution: Put layout: cover (and any cover props) inside the headmatter and remove the extra “cover frontmatter” slide.
Error: Slides render blank after changing a layout/component.
Cause: A layout/component crashed at runtime or required props are missing.
Solution: Preview in dev, identify the failing slide, simplify to layout: default, then reintroduce components incrementally until the break is found.
Error: The deck builds but pacing feels off (too dense, too slow, or missing a punchy hook).
Cause: The arc and slide blueprint weren’t explicit enough, so content drifted into walls of text.
Solution: Rebuild the blueprint: add section divider slides, promote key numbers into fact slides, split dense slides, and add progressive disclosure (v-clicks) where the speaker needs control.
Error: Web links provided, but the deck contains generic filler or misses key details.
Cause: Source material wasn’t distilled into concrete claims/stats/examples before drafting slides.
Solution: Re-run the source distillation step, extract 3–7 concrete claims + 2–4 stats + 1–3 demos, then update the blueprint and regenerate the affected slides.
Error: Slides read like article paragraphs with too much text, two-column bullet grids, or long descriptions.
Cause: Content was dumped onto the slide instead of being split across multiple slides and offloaded to presenter notes.
Solution: Apply the style guide. For each overloaded slide: (1) move explanatory text to presenter notes, (2) keep only the punchy hook or key visual on the slide, (3) split into 2-3 slides that build the story progressively. One idea per slide. If the slide has more than ~40 words of visible text, it needs splitting.
