---
name: slidev-deck
description: Scaffold, author, style, preview, and deploy dark-theme Slidev presentation decks with modular act files, custom Vue layouts, and embedded asciinema terminal recordings. Use when creating a new Slidev deck, authoring or refactoring slides and presenter notes, embedding .cast recordings or visual callouts, running or managing the local Slidev dev server, or configuring GitHub Pages deployment.
compatibility: Requires Node.js (v18+) and npm; integrates with Slidev (@slidev/cli) and asciinema-player v3
title: slidev-deck
canonical_url: https://skilld.dev/gh/domesticmouse/skills/slidev-deck
last_updated: 2026-11-20T07:06:09.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/agents/openai.yaml), [references/ASCIINEMA-INTEGRATION.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/references/ASCIINEMA-INTEGRATION.md), [references/SLIDE-PATTERNS.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/references/SLIDE-PATTERNS.md), [resources/acts/01-primer.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/acts/01-primer.md), [resources/components/AsciinemaPlayer.vue](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/components/AsciinemaPlayer.vue), [resources/deploy-slides.yml](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/deploy-slides.yml), [resources/layouts/cast-full.vue](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/layouts/cast-full.vue), [resources/layouts/hardware-callout.vue](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/layouts/hardware-callout.vue), [resources/layouts/skill-breakdown.vue](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/layouts/skill-breakdown.vue), [resources/package.json](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/package.json), [resources/slides.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/slides.md), [resources/style.css](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/style.css), [resources/vite.config.ts](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources/vite.config.ts), [scripts/slides-server.sh](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/scripts/slides-server.sh).
>
> If the user asked to install this Skill, run `npx skilld install domesticmouse/skills/slidev-deck`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/slidev-deck`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/domesticmouse/skills/slidev-deck) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/slidev-deck`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/slidev-deck --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/slidev-deck --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Slidev Deck

Procedural runbook, reusable Vue components/layouts, and server tooling for building high-signal technical slide decks with [Slidev](https://sli.dev/) (`slides/`), embedded `asciinema-player` terminal recordings, dark-mode typography, and static GitHub Pages deployment.

Works alongside `/asciinema` (recording, sanitizing, and trimming `.cast` files), `/ios-simulator-screenshot` (staging and verifying mobile simulator screen captures under `artifacts/screenshots/<project_name>/`), and `/crop-image` (trimming transparent margins and solid borders on slide images).

## Workflows

Choose the matching workflow based on your objective:

1. [Scaffold a New Slidev Deck](#1-scaffold-a-new-slidev-deck)
2. [Structure Modular Acts](#2-structure-modular-acts)
3. [Author Slides, Layouts & Presenter Notes](#3-author-slides-layouts--presenter-notes)
4. [Embed Terminal Recordings & Visual Assets](#4-embed-terminal-recordings--visual-assets)
5. [Run & Manage the Local Dev Server](#5-run--manage-the-local-dev-server)
6. [Verify Build & Deploy to GitHub Pages](#6-verify-build--deploy-to-github-pages)

---

### 1. Scaffold a New Slidev Deck

Initialize a new `slides/` workspace from the bundled templates in [`resources/`](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/resources):

1. Create the directory hierarchy and copy the starter configuration, theme stylesheet, component, and custom layouts:
   ```bash
   mkdir -p slides/{acts,components,layouts,public/casts,public/images}
   cp .agents/skills/slidev-deck/resources/package.json slides/package.json
   cp .agents/skills/slidev-deck/resources/vite.config.ts slides/vite.config.ts
   cp .agents/skills/slidev-deck/resources/style.css slides/style.css
   cp .agents/skills/slidev-deck/resources/slides.md slides/slides.md
   cp .agents/skills/slidev-deck/resources/acts/01-primer.md slides/acts/01-primer.md
   cp .agents/skills/slidev-deck/resources/components/AsciinemaPlayer.vue slides/components/AsciinemaPlayer.vue
   cp .agents/skills/slidev-deck/resources/layouts/*.vue slides/layouts/
   ```
2. Update the `--base /<repo-name>/` flag in `slides/package.json` (`"build": "slidev build --base /<repo-name>/"`) to match the repository name for GitHub Pages subpath hosting (or omit `--base` if deploying to a custom root domain).
3. Add `slides/node_modules/`, `slides/dist/`, `slides/.slidev.pid`, and `slides/.slidev.log` to `.gitignore`.
4. Install dependencies:
   ```bash
   npm --prefix slides install
   ```
5. *Completion Criterion*: `slides/node_modules/` is populated and `npm --prefix slides run build` exits with code 0.

---

### 2. Structure Modular Acts

Split multi-part presentations into Act-level markdown files under `slides/acts/` while keeping `slides/slides.md` as the master manifest:

1. Configure `slides/slides.md` with global presentation headmatter (`colorSchema: dark`, `background: '#121317'`, `highlighter: shiki`, `mdc: true`) and set `hide: true` on the headmatter block so Slidev does not insert a blank initial slide or leak headmatter fields into the first act:
   ```yaml
   ---
   theme: default
   background: '#121317'
   colorSchema: dark
   highlighter: shiki
   lineNumbers: false
   info: |
     ## Presentation Title
     Subtitle and Presenter Info
   drawings:
     persist: false
   transition: slide-left
   title: Presentation Title
   mdc: true
   hide: true
   ---

   ---
   src: ./acts/01-primer.md
   ---

   ---
   src: ./acts/02-core-story.md
   ---
   ```
2. Name act files sequentially (`01-primer.md`, `02-the-hook.md`, etc.) inside `slides/acts/`.
3. Tag every slide with a unique comment identifier immediately after its frontmatter block (e.g., `<!-- S01 -->`, `<!-- S12 -->`) to anchor edits and reviews.
4. *Completion Criterion*: `slides/slides.md` contains `hide: true` in its headmatter block and every `src: ./acts/...` entry resolves to a valid markdown file in `slides/acts/`.

---

### 3. Author Slides, Layouts & Presenter Notes

Follow the slide design conventions below. For copy-pasteable HTML/Markdown templates of every slide archetype, read [`references/SLIDE-PATTERNS.md`](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/references/SLIDE-PATTERNS.md).

#### Core Formatting Conventions:
1. **Clean Slide Headings**: Render slide titles using a clean flex header container without badges, pills, or Act chips:
   ```html
   <div class="flex items-center gap-3 mb-6">
     <h2 class="text-2xl font-bold m-0">Slide Title</h2>
   </div>
   ```
2. **Numbered Concept Lists**: Present multi-point explanations and comparisons as structured numbered lists (`<ol>`) with bold white titles and nested `<ul>` takeaways rather than cramped multi-card grids or dense multi-column tables:
   ```html
   <ol class="space-y-4 text-sm text-gray-200 list-decimal pl-6 mt-5 leading-relaxed">
     <li>
       <strong class="text-white">Topic / Feature Title</strong>
       <ul class="list-disc pl-5 mt-1 space-y-1 text-gray-300">
         <li>Primary high-signal takeaway or mechanism</li>
         <li>Secondary context or contrast</li>
       </ul>
     </li>
   </ol>
   ```
   When comparing 3–4 broad paradigms (e.g., MCP vs. Rules vs. Skills), give each concept its own focused numbered-list slide followed by a synthesis slide rather than squeezing all columns into one tiny table.
3. **Flush Code Fences Inside HTML**: Place markdown fenced code blocks (` ``` `) flush at column 0 with blank lines above and below whenever they sit inside HTML `<div>` wrappers. Indenting a fenced code block by 4+ spaces inside HTML causes Markdown to render raw tags instead of highlighted code.
4. **Conversational Presenter Notes**: Conclude every slide with an HTML comment (`<!-- ... -->`) containing natural spoken narrative that explains the transition and talking points behind each bullet. Write pure spoken prose without bracketed stage directions (`[Click]`, `[Next slide]`).

#### Choosing a Slide Layout:
- **`layout: center` (`class: text-center`)**: Title slide, Act divider slides, and big-quote callouts.
- **`layout: default`**: Concept lists, 2-column anti-pattern vs. solution cards (`bg-red-950/15` vs. `bg-emerald-950/15`), and code/architecture tables.
- **`layout: cast-full`**: Full-viewport interactive `asciinema-player` slide (`title`, `cast: /casts/file.cast`, `autoPlay: false`, `speed: 2.0`, `idleTimeLimit: 2.0`, `fit: both`, and optional `showChapterBar: true` during development).
- **`layout: skill-breakdown`**: Framed zoom-in card (`way: 1|2|3|mashup`, `title`).
- **`layout: hardware-callout`**: 12-column split pairing a framed image and optional caption overlay on the left (`title`, `image: /images/file.png`, `imageCaption`) with explanatory HTML content in the default slot on the right.

*Completion Criterion*: Every authored slide includes a clean `<h2>` header (or uses a dedicated layout header), unindented code fences with blank line separators, and a conversational `<!-- ... -->` speaker note block.

---

### 4. Embed Terminal Recordings & Visual Assets

Consult [`references/ASCIINEMA-INTEGRATION.md`](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/references/ASCIINEMA-INTEGRATION.md) for component props, Vite SSR rules, and base-path normalization details.

1. **Prepare & Embed `.cast` Recordings**:
   - Before executing a multi-cast **Recording Run**, use `/asciinema` (`.agents/skills/asciinema/references/RUNBOOK-FORMAT.md`) to generate an operator `RUNSHEET.md` from `TODO.md` or the slide blueprint (separating `recordings/raw/` from `recordings/final/` at `120x36` with paired **Before / After** `"m"` stop points).
   - Treat `recordings/final/<name>.cast` as the single source of truth. Use `/asciinema` to sanitize secrets (`sanitize-cast.py`), strip trailing shell exit prompts (`trim-cast.py --in-place`), and place/verify `"m"` chapter stop points (`mark-cast.py --list` / `--set`) on the canonical recording in `recordings/final/`, then run `npm --prefix slides run sync-casts` (also executed automatically by `predev` and `prebuild`) to sync `recordings/final/*.cast` into `slides/public/casts/`.
   - For shell commands and TUI launchers in `zsh` (e.g. `flutter create ...`, `git init && ...`, `agy`), place command-entry stop points on the typed/pasted command text rather than post-launch banners; `mark-cast.py` automatically advances past bracketed-paste reverse video (`[REV]`) to the un-reversed redraw (`[UNREV]`) and splits trailing `\x1b[1B\r\x1b[K` cursor-down sequences into a post-marker `"o"` event (`dt=0.02s`) so the cursor stays on the same line at the end of the command.
   - Reference recordings with root-relative paths in slide frontmatter:
     ```yaml
     ---
     layout: cast-full
     title: "Recording Title"
     cast: /casts/demo.cast
     autoPlay: false
     speed: 2.0
     idleTimeLimit: 2.0
     fit: both
     ---
     ```
   - `AsciinemaPlayer.vue` compiles each breakpoint-bounded segment to run at `>= speed` (default `2.0x`) and complete in `<= maxSegmentDuration` (default `30s`). By default in final presentation slides (`showChapterBar: false`), it renders a clean minimalist `Playback speed: Nx` badge beneath the terminal while supporting `[` / `]` / `p` stage hotkeys; set `showChapterBar: true` in slide frontmatter during development to display interactive chapter stepper pills, transport controls, and segment metadata.
2. **Prepare & Embed Images**:
   - For mobile app runs, use `/ios-simulator-screenshot` (`xcrun simctl io booted screenshot /abs/path/to/repo/artifacts/screenshots/<project_name>/<file>.png` with full absolute paths) to stage clean device-framebuffer screenshots per run in `artifacts/screenshots/<project_name>/`.
   - Use `/crop-image` (`crop.py --inspect` / `--autocrop`) to verify dimensions or remove excess transparent margins/solid borders before copying presentation-ready images into `slides/public/images/`.
   - Reference images via `image: /images/<filename>` in `hardware-callout` slides.
3. **Preserve `BASE_URL` Resolution in Custom Vue Files**:
   - In any custom Vue layout or component that loads local assets from `slides/public/`, normalize paths with `import.meta.env.BASE_URL` so assets resolve on both local dev (`/`) and GitHub Pages subpaths (`/<repo-name>/`).
4. *Completion Criterion*: All `/casts/*` and `/images/*` paths referenced in `slides/acts/*.md` exist in `slides/public/{casts,images}/`.

---

### 5. Run & Manage the Local Dev Server

Manage the background Slidev development server using the bundled [`scripts/slides-server.sh`](https://skilld.dev/api/skills-raw/domesticmouse/skills/slidev-deck/scripts/slides-server.sh) utility:

```bash
# Start server on default port 3030 (auto-installs node_modules if missing)
.agents/skills/slidev-deck/scripts/slides-server.sh start

# Check server PID, HTTP status, and navigation URLs
.agents/skills/slidev-deck/scripts/slides-server.sh status

# Restart or stop the server
.agents/skills/slidev-deck/scripts/slides-server.sh restart
.agents/skills/slidev-deck/scripts/slides-server.sh stop

# Use a custom port if 3030 is in use
.agents/skills/slidev-deck/scripts/slides-server.sh start -p 3040
```

#### Live Slidev Endpoints:
- **Presentation Deck**: `http://localhost:3030/`
- **Presenter Console** (speaker notes, timer, next slide): `http://localhost:3030/presenter`
- **Slide Overview Grid**: `http://localhost:3030/overview`

*Completion Criterion*: Running `.agents/skills/slidev-deck/scripts/slides-server.sh status` reports `RUNNING` with `HTTP: 200` (or `304`).

---

### 6. Verify Build & Deploy to GitHub Pages

1. Run the static production build to verify that all Vue components, layouts, Shiki code blocks, and Markdown slides compile cleanly:
   ```bash
   npm --prefix slides run build
   ```
2. To configure automated GitHub Pages deployment, copy the workflow template into `.github/workflows/deploy-slides.yml`:
   ```bash
   mkdir -p .github/workflows
   cp .agents/skills/slidev-deck/resources/deploy-slides.yml .github/workflows/deploy-slides.yml
   ```
   Ensure `on.push.paths` in `.github/workflows/deploy-slides.yml` includes every upstream directory synced by `prebuild` (e.g., `'slides/**'`, `'recordings/final/**'`, and any external tutorial or asset folders) so pushing changes to those files triggers the GitHub Pages workflow.
3. Ensure repository GitHub Pages settings are configured with **Build and deployment > Source: GitHub Actions**.
4. *Completion Criterion*: `npm --prefix slides run build` exits with returncode 0 and generates `slides/dist/index.html`.
