Slidev Generator

Purpose

Create Slidev decks through a staged decision process: analyze the content, classify the deck archetype, ask the user to choose a visual style, recommend conservative addons for that style and content, then generate a maintainable Slidev project where slides.md imports chapter files from pages/. Generated decks should have deliberate visual hierarchy, clearly marked key points, and restrained Slidev animations that support the talk rhythm without competing with the content.

This skill complements the official Slidev skill. The official skill is the syntax and capability reference; this skill is the production workflow for choosing a theme/addons, structuring a deck, scaffolding files, and keeping the result maintainable.

Non-Negotiable Rules

• Use exactly one Slidev theme per project and zero or more addons.
• Prefer split decks: keep global deck config and page order in slides.md, and write slide bodies in pages/*.md imported with src.
• Put the first page import as src: ./pages/01-opening.md inside the global headmatter. Otherwise Slidev treats the config-only first block as a blank first slide. Put later imports in tight three-line blocks: ---, then src: ./pages/file.md, then ---.
• Use Slidev's built-in presenter notes with the last HTML comment block in a slide. Do not add @slidev/plugin-notes; that package is not published on npm.
• Do not start a frontend dev server unless the user explicitly asks. When asked to start one, check the relevant port first and follow the repository instructions.
• Do not run full lint, full build, full export, full test, or whole-repo commands unless the user explicitly asks.
• Do not force the user to know addon names. Recommend a default addon set, then ask what to keep or remove.
• Warn that Slidev PPTX export is screenshot-based and is not the same as a native editable PowerPoint deck.
• Do not generate a static wall of content unless the user explicitly asks for a static/export-first deck. Every deck needs slide transitions plus meaningful in-slide reveals or motion where they improve comprehension.
• Keep emphasis and in-slide animation restrained, precise, and timely. Use the smallest effect that makes the idea clear; never let animation or styling become the subject of the slide.
• Every non-cover content slide needs a clear primary takeaway. Mark it visually with layout, scale, contrast, callout styling, an annotation, or a staged reveal.

First Files To Read

• For current official facts, consult references/official-slidev-notes.md.
• For the style-selection phase, consult references/theme-presets.md.
• For addon recommendations, consult references/addon-presets.md.
• For project generation details and split-page examples, consult references/project-workflow.md.
• For slide narrative and layout quality, consult references/deck-quality.md.
• For animation and key-point emphasis patterns, consult references/animation-and-emphasis.md.
• For showcase-informed writing patterns and deck archetypes, consult references/showcase-writing-patterns.md.

Workflow

1. Intake And Deep Content Analysis

Accept either:

• A presentation topic plus rough requirements
• A Markdown document, notes, article, meeting memo, research summary, or outline
• An existing Slidev project or slides.md

Analyze before asking questions:

• Audience: developers, leadership, customers, students, researchers, mixed
• Deck type: technical talk, tutorial, architecture review, product showcase, research report, business summary, workshop, visual story
• Deck archetype: technical-talk, architecture-review, product-demo, research-report, or course-workshop
• Content shape: argument, chronological story, system explanation, how-to, comparison, report
• Visual needs: code, diagrams, screenshots, data, quotes, speaker notes, QR/contact slide
• Emphasis needs: the core claim, key number, decision, risk, comparison winner, or step that must not be missed
• Animation needs: what appears first, what should be revealed on clicks, what should stay static, and where motion would clarify a process
• Risk areas: overlong sections, unsupported assets, too many diagrams, export needs

Use references/showcase-writing-patterns.md to map the content to an archetype before recommending style or addons. The archetype controls the default storyboard rhythm, page grouping, and validation expectations.

Then ask for style preference as Phase 1. If the user already gave a style, still show the nearest preset and one or two alternatives unless the user explicitly says not to ask.

2. Phase 1 - Ask For Style Preference

Present 3-5 concrete style options from references/theme-presets.md. For each option include:

• Style name and style_id
• One-sentence mood description
• Recommended Slidev theme
• Where it works best
• Default addon direction, not the final addon list
• A thumbnail reference if useful. Resolve the skill folder path and show the matching asset from assets/style-*.svg.

Ask the user to choose one style before continuing. Keep this question focused on style only.

3. Phase 2 - Recommend Addons

After the user picks a style, recommend addons from references/addon-presets.md based on:

• The selected style preset
• The selected deck archetype
• Deck type and content needs
• Whether the user needs export reliability
• Whether the deck needs speaker notes, QR codes, hand-drawn diagrams, arrows, charts, or runnable code

Start with built-in Slidev capabilities, the chosen theme, local Markdown/HTML/UnoCSS, Iconify dependencies, and local Vue components. Recommend a Slidev addon only when it solves a visible presentation need.

Present:

• Default addons to keep
• Optional addons to consider
• Addons to avoid for this deck
• Built-in capabilities and non-addon dependencies such as Iconify icon packs
• A plain-language explanation of each addon

Ask the user which addon set to use. Offer a recommended default so the user can accept it without knowing the ecosystem.

4. Phase 3 - Check Or Create A Project

Inspect the current workspace or the directory requested by the user:

• Existing Slidev project indicators: slides.md, package.json with @slidev/cli or slidev, pages/, components/, .slidev/
• If there is an existing project, read slides.md, package.json, and relevant pages/*.md before editing.
• If there is no usable project, scaffold a minimal one.

Use scripts/init-slidev-project.mjs when a deterministic scaffold is enough:

node path/to/slidev-generator/scripts/init-slidev-project.mjs --dir ./my-deck --title "Deck Title" --theme seriph --archetype technical-talk --addons "fancy-arrow"

If the chosen addon set is empty, omit --addons entirely instead of passing an empty string. Empty string arguments can be shell-dependent, especially in PowerShell.

The script creates or updates:

• package.json
• slides.md
• pages/01-opening.md
• pages/02-context.md
• pages/03-mechanism.md
• pages/04-evidence.md
• pages/99-closing.md

It updates dependency declarations but does not install packages, run builds, export, or start a server.

5. Phase 4 - Storyboard The Deck

Before writing files, create a concise storyboard. For each slide, decide:

• Title or visible heading
• Primary takeaway
• Layout or composition pattern
• Click steps and what each step reveals
• Visual asset, code block, diagram, or component need
• Speaker note need
• Target chapter file in pages/

Keep the storyboard aligned to the selected archetype rhythm from references/showcase-writing-patterns.md. This prevents static walls of Markdown and avoids adding animation after the fact.

6. Phase 5 - Generate The Deck

Generate files in this shape:

deck/
├── package.json
├── slides.md
├── pages/
│   ├── 01-opening.md
│   ├── 02-context.md
│   ├── 03-mechanism.md
│   ├── 04-evidence.md
│   └── 99-closing.md
├── components/
└── public/

Keep slides.md short:

---
theme: seriph
title: "Deck Title"
addons:
  - fancy-arrow
transition: slide-left
clickAnimation: fade
mdc: true
src: ./pages/01-opening.md
---

---
src: ./pages/02-context.md
---

The import format is fragile. Slidev's first frontmatter block is also the first slide's configuration. If it contains only deck config and the first src appears in the next block, Slidev can render an empty first slide. If src: appears as plain body text, Slidev can display src: ./pages/... instead of importing. After any manual edit to slides.md, check that the first import is inside the global headmatter and later imports are exactly wrapped by their own --- delimiters.

Rules for page files:

• Each page file is a narrative chapter and may contain 1-4 tightly coupled slides.
• Prefer one main idea per slide.
• Keep page filenames numbered and descriptive.
• Give each non-cover content slide an explicit visual hierarchy: title, primary takeaway, support, detail.
• Use v-clicks for bullet/list reveals, v-click and v-after for paired reveals, code-line click ranges for walkthroughs, and v-motion only where spatial movement clarifies the idea.
• Keep the first view meaningful. Do not hide the slide title or every important object behind clicks.
• Keep most slides to 2-4 clicks. Use clicks frontmatter only when Slidev's automatic click count is not enough.
• Prefer restrained default click animations such as fade, up, or a single directional cue. Avoid stacked modifiers and novelty animation unless they directly explain movement, sequence, or contrast.
• Use speaker notes only where the user needs rehearsal or delivery support.
• Put shared Vue components in components/ only when repeated structure justifies it.
• Put user-supplied or generated images in a folder next to the importing page, such as pages/assets/, and reference them with page-relative paths like ./assets/image.png. Avoid leading-slash asset paths in imported page files on Windows because Vite can resolve /image.png to the drive root.
• When generating Iconify components such as <carbon:logo-github />, add the matching @iconify-json/<collection> package dependency.

7. Phase 6 - Animation And Emphasis Pass

Before validation, make a focused pass over generated pages/*.md:

• Identify the sentence, number, decision, risk, or diagram element each slide wants the audience to remember.
• If it is not visually obvious, rewrite the slide using a fact, statement, quote, two-column contrast, callout, bold/large type, border accent, arrow annotation, or similar emphasis pattern.
• If a slide has several supporting bullets, steps, code lines, diagram nodes, or comparison points, stage them with Slidev click animations only at the moment the presenter needs them.
• If a slide already works as a single static image or title moment, keep animation minimal but preserve a clear slide transition.
• Avoid making every element animated. Animation should reveal structure, timing, and emphasis, not decorate the page.

8. Focused Validation

After generating, use targeted checks only:

node path/to/slidev-generator/scripts/validate-slidev-deck.mjs --dir ./my-deck

This checks the current deck structure, malformed src import blocks, and obvious maintainability issues. It is not a full build and does not start services.

If a broader check is needed, explain why, name the exact command, and wait for explicit user approval.

9. Final User Instructions

At the end, tell the user how to run it themselves:

npm install
npm run dev

or the detected package manager equivalent.

Do not start the server automatically. If the user asks for startup in a later message, check the port first.

Expected Behavior

When the user provides a topic or Markdown document, do not immediately generate the whole project. First analyze the content, classify the archetype, and ask Phase 1 style preference. After the user chooses a style, ask Phase 2 addon selection. Only then storyboard, scaffold or update the Slidev project, and write the split chapter files.

When the user explicitly says "use the recommended default" or "do not ask me", choose the closest style and addon preset, then proceed.