Agent-Skills.md

Agent Skills: Slidev - Presentation Slides for Developers

>

UncategorizedID: geggo98/dotfiles/slidev

Repository

geggo98/dotfiles
geggo98License: CC0-1.0
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/geggo98/dotfiles/tree/HEAD/modules/ai/_files/skills/slidev

Skill Files

Browse the full folder contents for slidev.

Download Skill

Loading file tree…

modules/ai/_files/skills/slidev/SKILL.md

Skill Metadata

Name
slidev
Description
>

Slidev - Presentation Slides for Developers

Usage

Run the script:

zsh ${CLAUDE_SKILL_DIR}/scripts/find-slidev-port.sh $ARGUMENTS

Web-based slides maker built on Vite, Vue, and Markdown.

When to Use

  • Technical presentations or slidedecks with live code examples
  • Syntax-highlighted code snippets with animations
  • Interactive demos (Monaco editor, runnable code)
  • Mathematical equations (LaTeX) or diagrams (Mermaid, PlantUML)
  • Record presentations with presenter notes
  • Export to PDF, PPTX, or host as SPA
  • Code walkthroughs for developer talks or workshops

Quick Start

bun create slidev     # Create project
bun run build         # Build static SPA
bun run export        # Export to PDF (requires playwright-chromium)

Dev Server (always use tmux skill)

The Slidev dev server needs a full TTY and will not run as a plain background subprocess of the agent. Start it through the tmux skill (Skill(tmux)), whose wrapper is tmux-use.sh (NOT claude-tmux.sh) — never use raw tmux commands with variable expansion. From this skill, reach the sibling tmux skill at ${CLAUDE_SKILL_DIR}/../tmux/scripts/tmux-use.sh.

IMPORTANT: Always specify --port explicitly (e.g. --port 3030). Without it, Slidev auto-picks a free port in 3030–4000, making it hard to find the server later. See port-detection for details.

If the port was forgotten, run ${CLAUDE_SKILL_DIR}/scripts/find-slidev-port.sh to scan for running Slidev instances.

TMUX="${CLAUDE_SKILL_DIR}/../tmux/scripts/tmux-use.sh"   # the tmux skill's wrapper

# Start the dev server in a tmux session (always pass --port!). Run from the
# project root so `bun run dev` resolves the project's package.json.
zsh "$TMUX" new -s claude-slidev -c 'cd /path/to/project && bun run dev -- --port 3030 ./<talk>/slides.md'

# Wait until it is serving, then show the user how to monitor it
zsh "$TMUX" wait -p 'localhost:3030' -T 60
zsh "$TMUX" attach          # prints the `tmux -S … attach` command for the user
zsh "$TMUX" capture         # read recent server output (build errors etc.)

Verify: After the dev server is ready, confirm slides load at http://localhost:3030 with the browser-use skill. After bun run export, check the output PDF exists in the project root.

Debugging: Use Playwright for debugging issues with individual slides. It's much faster and more reliable than browser-use. Always place test scripts and screenshots in ./playwright-tests/ within the project directory (never in /tmp).

IMPORTANT: Use the Write tool to create scripts and the .gitignore — never use cat <<HEREDOC, shell redirects, or echo to write files (these trigger sandbox security warnings). Run scripts with bun run playwright-tests/script.ts or bunx playwright test.

On first use, create playwright-tests/.gitignore via the Write tool with content: *\n!.gitignore

Then write scripts like playwright-tests/debug-slide-5.ts via the Write tool and run them with bun run. Screenshots land in playwright-tests/ as well. Users can git add -f individual files they want to keep.

Overflow & visual QA: Slidev silently clips anything past the slide canvas. After authoring content-heavy slides, run the bundled checker — it renders each slide at 1280×720 across chromium + firefox + webkit (clipping is layout-engine-specific), cycles tabs, checks light + true dark, and reports content past the canvas plus code hidden below the Monaco fold:

zsh ${CLAUDE_SKILL_DIR}/scripts/check-slide-overflow.sh 1-40 3030               # check a range, all 3 engines
zsh ${CLAUDE_SKILL_DIR}/scripts/check-slide-overflow.sh 1-40 3030 --shot ./playwright-tests/qa   # + per-engine screenshots for vision QA
zsh ${CLAUDE_SKILL_DIR}/scripts/check-slide-overflow.sh 1-40 3030 --browsers chromium   # narrow for fast iteration
zsh ${CLAUDE_SKILL_DIR}/scripts/check-slide-overflow.sh 1-90 3030 --max-concurrency 3   # weak/contended dev server

The engines run in parallel (engine × theme lanes; each page boots once then navigates in-SPA), so a full cross-browser sweep is several times faster than a serial pass while staying correctness-safe; tune with --max-concurrency N (default min(lanes,4)) and --jobs N (pages per lane). Browsers are nix-pinned (playwright-driver.browsers, with playwright install as fallback). See testing-overflow for the why and the technique. (Needs deno; nix for pinned browsers.)

Cleanup: When done, kill the session: zsh "$TMUX" kill -s claude-slidev.

Basic Syntax

---
theme: default
title: My Presentation
---

# First Slide

Content here

---

# Second Slide

More content

<!--
Presenter notes go here
-->
  • --- separates slides
  • First frontmatter = headmatter (deck config)
  • HTML comments = presenter notes

Core References

| Topic | Description | Reference | |-------|-------------|-----------| | Markdown Syntax | Slide separators, frontmatter, notes, code blocks | core-syntax | | Animations | v-click, v-clicks, motion, transitions | core-animations | | Headmatter | Deck-wide configuration options | core-headmatter | | Frontmatter | Per-slide configuration options | core-frontmatter | | CLI Commands | Dev, build, export, theme commands | core-cli | | Components | Built-in Vue components | core-components | | Sections & TOC | Chapter dividers, <Toc>, and hideInToc | authoring-sections-toc | | Layouts | Built-in slide layouts | core-layouts | | Exporting | PDF, PPTX, PNG export options | core-exporting | | Hosting | Build and deploy to various platforms | core-hosting | | Global Context | $nav, $slidev, composables API | core-global-context | | Testing | E2E testing with Playwright | testing-playwright | | Overflow & Visual QA | Canvas scaling, overflow/clipping detection, dark-mode caveats | testing-overflow | | Port Detection | How Slidev picks ports, finding running instances | port-detection |

Feature Reference

Code & Editor

| Feature | Usage | Reference | |---------|-------|-----------| | Line highlighting | ```ts {2,3} | code-line-highlighting | | Click-based highlighting | ```ts {1\|2-3\|all} | code-line-highlighting | | Line numbers | lineNumbers: true or {lines:true} | code-line-numbers | | Scrollable code | {maxHeight:'100px'} | code-max-height | | Code tabs | ::code-group (requires comark: true) | code-groups | | Monaco editor | ```ts {monaco} | editor-monaco | | Run code | ```ts {monaco-run} | editor-monaco-run | | Edit files | <<< ./file.ts {monaco-write} | editor-monaco-write | | Monaco in Vue | <Monaco :codeLz="..." /> in components | editor-monaco-custom-vue | | Code animations | ````md magic-move | code-magic-move | | TypeScript types | ```ts twoslash | code-twoslash | | Import code | <<< @/snippets/file.js | code-import-snippet |

Diagrams & Math

| Feature | Usage | Reference | |---------|-------|-----------| | Mermaid diagrams | ```mermaid | diagram-mermaid | | PlantUML diagrams | ```plantuml | diagram-plantuml | | LaTeX math | $inline$ or $$block$$ | diagram-latex |

Layout & Styling

| Feature | Usage | Reference | |---------|-------|-----------| | Canvas size | canvasWidth, aspectRatio | layout-canvas-size | | Zoom slide | zoom: 0.8 | layout-zoom | | Scale elements | <Transform :scale="0.5"> | layout-transform | | Layout slots | ::right::, ::default:: | layout-slots | | Scoped CSS | <style> in slide | style-scoped | | Global layers | global-top.vue, global-bottom.vue | layout-global-layers | | Draggable elements | v-drag, <v-drag> | layout-draggable | | Icons | <mdi-icon-name /> | style-icons | | Dark/Light mode | dark:, useDarkMode(), colorSchema | style-dark-light-mode |

Animation & Interaction

| Feature | Usage | Reference | |---------|-------|-----------| | Click animations | v-click, <v-clicks> | core-animations | | Rough markers | v-mark.underline, v-mark.circle | animation-rough-marker | | Drawing mode | Press C or config drawings: | animation-drawing | | Direction styles | forward:delay-300 | style-direction | | Note highlighting | [click] in notes | animation-click-marker |

Syntax Extensions

| Feature | Usage | Reference | |---------|-------|-----------| | Comark syntax | comark: true + {style="color:red"} | syntax-comark | | Block frontmatter | ```yaml instead of --- | syntax-block-frontmatter | | Import slides | src: ./other.md | syntax-importing-slides | | Merge frontmatter | Main entry wins | syntax-frontmatter-merging |

Presenter & Recording

| Feature | Usage | Reference | |---------|-------|-----------| | Recording | Press G for camera | presenter-recording | | Timer | duration: 30min, timer: countdown | presenter-timer | | Remote control | slidev --remote | presenter-remote | | Ruby text | notesAutoRuby: | presenter-notes-ruby |

Export & Build

| Feature | Usage | Reference | |---------|-------|-----------| | Export options | slidev export | core-exporting | | Build & deploy | slidev build | core-hosting | | Build with PDF | download: true | build-pdf | | Cache images | Automatic for remote URLs | build-remote-assets | | OG image | seoMeta.ogImage or og-image.png | build-og-image | | SEO tags | seoMeta: | build-seo-meta |

Export prerequisite: bun add -D playwright-chromium is required for PDF/PPTX/PNG export. If export fails with a browser error, install this dependency first.

Lifecycle scripts are disabled machine-wide (~/.npmrc, ~/.bunfig.toml — see modules/supply-chain-hardening.nix), and playwright-chromium downloads its browser from an install script. So bun add reports success while no browser is fetched, and the failure only surfaces at export time. Opt out for this project with a local .npmrc — bun reads it and it outranks the global settings:

# .npmrc in the project root
ignore-scripts=false

Then re-run bun add -D playwright-chromium. A local bunfig.toml with ignoreScripts = false does not work here (the global ~/.npmrc still wins), and neither does bun install --trust. Keep the opt-out project-local; do not lift it globally.

A deck that gets its browsers from Nix needs no opt-out: with PLAYWRIGHT_BROWSERS_PATH set (and PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1), the install script has nothing left to do — see Nix-pinned browsers. There the version coupling is what breaks exports instead: the npm playwright* packages must be pinned to the exact version playwright-driver ships.

Editor & Tools

| Feature | Usage | Reference | |---------|-------|-----------| | Side editor | Click edit icon | editor-side | | VS Code extension | Install antfu.slidev | editor-vscode | | Prettier | prettier-plugin-slidev | editor-prettier | | Eject theme | slidev theme eject | tool-eject-theme |

Lifecycle & API

| Feature | Usage | Reference | |---------|-------|-----------| | Slide hooks | onSlideEnter(), onSlideLeave() | api-slide-hooks | | Navigation API | $nav, useNav() | core-global-context |

Common Layouts

| Layout | Purpose | |--------|---------| | cover | Title/cover slide | | center | Centered content | | default | Standard slide | | two-cols | Two columns (use ::right::) | | two-cols-header | Header + two columns | | image / image-left / image-right | Image layouts | | iframe / iframe-left / iframe-right | Embed URLs | | quote | Quotation | | section | Section divider | | fact / statement | Data/statement display | | intro / end | Intro/end slides |

Resources

  • Documentation: https://sli.dev
  • Theme Gallery: https://sli.dev/resources/theme-gallery
  • Showcases: https://sli.dev/resources/showcases