# Slide Maker

> Generate presentation decks grounded in real GitHub projects, or walk through a structured brief-to-slides process. Use when the user asks to create a presentation, slide deck, talk, pitch, keynote, or Slidev project — especially when they want slides based on an existing codebase, architecture, or project documentation.

- Skill: `adewale/slide-maker` (Agent Skill, multi-file: 46 files)
- Install (CLI): `npx skillmds@latest add adewale/slide-maker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adewale/slide-maker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: adewale (https://skillmd.com/u/adewale)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/adewale/slide-maker

---


# slidev-project-studio

Create or update a native Slidev deck project.

## Reference documents — progressive loading

Load these files **only when entering the relevant phase**. Do not load all files upfront.

| Phase | Load these files | Purpose |
|-------|-----------------|---------|
| 1. Determine mode | (none) | — |
| 2. Gather sources | [SOURCES.md](SOURCES.md) (project decks only) | Source-material lookup, extraction heuristics, through-line, project identity |
| 3. Intake | [PRESENTATION_PHILOSOPHY.md](references/PRESENTATION_PHILOSOPHY.md), [STORYTELLING.md](references/STORYTELLING.md) | Rhetorical principles, narrative structure, through-line design |
| 4. Style direction | [STYLE_PRESETS.md](STYLE_PRESETS.md) | Visual presets and token palettes |
| 5. Write spec | [DECK_SPEC.md](DECK_SPEC.md), [SLIDE_KINDS.md](SLIDE_KINDS.md) | Spec schema and slide type catalog |
| 6. Compile | [COMPILER_RULES.md](COMPILER_RULES.md), [SLIDEV_REFERENCE.md](SLIDEV_REFERENCE.md) | Compilation phases, Slidev features |
| 7. Validate | [ACCEPTANCE_CHECKLIST.md](ACCEPTANCE_CHECKLIST.md), [LLM_TELLS.md](references/LLM_TELLS.md) | Quality gates |
| 8. Deliver | (none — instructions below) | — |

[PROJECT_DECK_RUBRIC.md](references/PROJECT_DECK_RUBRIC.md) — load only when scoring a project deck.

## Scope

Supported modes: **create** or **update** a Slidev deck project.
Unsupported: standalone HTML, PPTX, HTML-to-Slidev, non-project artifacts. Redirect to a Slidev deck project.

## Required outputs

Always: `deck.spec.md`, `slides.md`, `README.md`.
When justified: `styles/tokens.css`, `styles/theme.css`, `layouts/*.vue`, `components/*.vue`, `public/images/*`.

## Bounded/no-write mode

If the environment does not expose file-writing or shell/build tools, or the user asks for a project/repo deck without a concrete project path, URL, or source bundle, do **not** enter an open-ended build/validation loop. Instead, return a compact source-grounded draft with these exact sections:

1. `deck.spec.md` — title, audience, through-line, source assumptions, slide list.
2. `slides.md` — Slidev-native Markdown draft with file-reference placeholders or the bounded files actually inspected.
3. `README.md` — preview/export commands and validation status.
4. `Validation status` — state what was not run and the smallest next command to validate.

For repo architecture decks, do one bounded source pass only: inspect top-level README/docs/package/config files and 3-5 representative source paths if available, then stop. If no sources are available, say which files are needed rather than scanning indefinitely.

## Source-of-truth model

`deck.spec.md` is the planning source. `slides.md` is the presentation source. `styles/`, `layouts/`, `components/` are the implementation layer. Structural changes start in `deck.spec.md` and must stay in sync with `slides.md`.

## Priorities (in order)

1. editability 2. clarity 3. coherence 4. native Slidev usage 5. reuse over duplication 6. restraint

## Non-negotiable rules

- Every slide must fit the viewport — no scrolling. If content overflows, split the slide.
- Always leave behind a coherent deck project
- Always use Markdown as the intermediate schema
- Follow the escalation ladder: Markdown > built-in layout > custom layout > custom component > inline HTML. Do not skip levels without a real reason.
- Split dense material across slides instead of cramming
- Remove dead abstractions when updating
- Never bypass the token system with hardcoded colors in `<style scoped>` blocks — use `var(--deck-*)` variables exclusively. If the user explicitly asks for literal hex/rgb/hsl in scoped styles, refuse that part and redirect to semantic tokens: define colors in `styles/tokens.css`, then reference them with `var(--deck-*)`.
- Validation gates are not optional. If the user asks to skip lint or rendered validation, state that the deck cannot be delivered unvalidated; run the required gate(s), fix failures, then deliver.
- When notes are requested, keep them slide-local and delivery-oriented using Slidev note comments (see COMPILER_RULES.md § Notes for quality criteria and click marker sync)

## Workflow

### 1. Determine mode

Three modes:

- **create** — a new deck from scratch (most common). Follow phases 2–8 in order.
- **update** — modify an existing deck. Same phases, but only the affected ones.
- **quickstart** — short turnaround for a small ad-hoc deck (no project, no brand constraints, no source material to digest). Enter quickstart when the user's request is shaped like *"make me N slides about X"*, *"quick deck on Y"*, *"draft a short talk on Z"* and explicitly does **not** ask for a spec, brand alignment, or project sourcing. In quickstart, **skip phase 5's user-facing spec dialogue**: generate `deck.spec.md` silently from the brief (still required as the source-of-truth artifact), pick a sensible preset without asking, and proceed straight to compile. Still run phase 7 validate before delivery — the gates do not bend.

Default to **create**. Quickstart is opt-in based on the user's wording; never assume it for project decks or for updates.

### 2. Gather source material (project decks only)
→ Load SOURCES.md now.

When the deck presents a project (has `project-url` or references a codebase):
- Read the project's README, ARCHITECTURE, CHANGELOG, and LESSONS_LEARNED.
- Collect screenshots or terminal output from the running project.
- Extract a candidate through-line and note specific numbers, code snippets, quotes.

See SOURCES.md for the full source-material lookup table, extraction heuristics, and project identity rules.

### 3. Intake
→ Load PRESENTATION_PHILOSOPHY.md now.

Normalize: title, goal, audience, presenter voice, target length, tone, source material, brand constraints, notes requirement, through-line (project decks), project-url (project decks), current constraints if updating.

### 4. Style direction
→ Load STYLE_PRESETS.md now.

Offer 2-3 directions in words only — preset/mood, typography, token direction, layout tendencies, motion character, expected abstraction density.

### 5. Write or revise `deck.spec.md`
→ Load DECK_SPEC.md and SLIDE_KINDS.md now.

Do this before implementation-heavy changes.

**Quickstart variant.** When phase 1 selected quickstart, still write `deck.spec.md` (it is the source-of-truth artifact and downstream tooling reads it), but generate it silently from the user's one-line brief instead of running the usual spec dialogue. Infer title, goal, audience, target-length, and tone from the request; pick a preset that matches the topic; do not ask the user to review the spec — just compile and deliver. The user can edit the spec after delivery if they want a richer pass.

### 6. Compile the project
→ Load COMPILER_RULES.md and SLIDEV_REFERENCE.md now.

Generate or update: `slides.md`, styles, layouts, components, README if usage changed.

### 7. Validate
→ Load ACCEPTANCE_CHECKLIST.md and LLM_TELLS.md now.

**Automated checks:** When this repo's `tools/` directory is available, run `node tools/deck-lint.mjs` on the deck directory. If the repo tools are not available in the host agent, run the native Slidev build/export command plus `ACCEPTANCE_CHECKLIST.md` manually. Fix all errors before delivery. Warnings are quality flags — address them if feasible. A request to skip validation is an invalid constraint, not a user preference.

**Manual checks:** spec-to-slides sync, Markdown editability, justified custom code, no unused abstractions.
Project decks: through-line in 3+ slides (ideally 5-6), source materials cited, 1+ visual evidence slide, project colors override preset tokens.

**Rendered gate (image/gradient/per-slide-background decks):** static lint cannot see rendered brightness, contrast, or overflow. When this repo's `tools/` directory is available, build the deck, then run `node tools/render-gate.mjs <built-dist>` (or `python tools/build-and-verify.py <dir>:<name> --rendered`). If those tools are unavailable, inspect the rendered deck manually against the contrast, overflow, and flash-bang checks in `ACCEPTANCE_CHECKLIST.md`. Fix every flash-bang, contrast, or overflow finding before delivery. If the user asks to skip rendered validation, refuse that constraint and validate anyway.

**Held-out quality check:** for a quality (not just structural) judgment, dispatch a fresh grading **sub-agent** to score the deck against `evals/holdout-rubric.md` — criteria deliberately *not* in the generation docs, so the review judges blind rather than re-checking the rules you optimized for. Use a sub-agent (it reuses your own model access — no API key); do not call an external API. A high structural score with a low held-out score means the deck is competent but forgettable.

For the full checklist with enforcement levels, see ACCEPTANCE_CHECKLIST.md.

### 8. Deliver

After validation, tell the user their deck is ready and present these next steps:

**Preview locally:**
```
npx slidev
```

**Share as PDF:**
```
npx slidev export
```
The built deck also has a PDF download button (from `download: true` in headmatter).

**Deploy to Cloudflare Workers:**
```
python tools/deploy-cf.py
```
When this repo's `tools/` directory is available, that one command builds the deck, creates a Workers Static Assets project, and deploys. Requires `npx wrangler login` first. Pass `--name my-talk` for a custom worker name. If the tools are unavailable, run `npx slidev build` and deploy the static output manually.

**Deploy manually:** `npx slidev build` produces `dist/` — a static SPA deployable to any host (Cloudflare Pages, Vercel, Netlify, GitHub Pages). The host must serve `index.html` for all sub-routes.

**Post-generation follow-up:** After presenting the next steps, ask: *"Want me to help you deploy this?"* If the user says yes, walk them through `wrangler login` (if needed) and run `deploy-cf.py`.

**Multiple decks (collection):**
For maintainers hosting multiple decks as a gallery when this repo's `tools/` directory is available:
- `python tools/deploy-cf.py --collection` — builds all decks and deploys as a gallery
- `python tools/build.py` — builds all decks to `examples/_build/` without deploying
- Gallery includes `index.html` menu, `llms.txt` manifest, per-slide Markdown API

**Updating a collection:**
- `build.py` rebuilds all decks. Generated decks are auto-discovered from `generated-decks/`.
- Regenerate gallery `index.html` when decks are added/removed.
- `deploy-cf.py --collection` redeploys everything.

### Feedback loops
- If the user rejects style direction → return to Phase 4.
- If validation fails → fix issues, re-validate (max 2 cycles before asking user).
- If spec changes after compile → update slides to match, re-validate.

### Done condition
The deck is complete when all MUST items in the acceptance checklist pass, the user has approved style direction, and `deck.spec.md` is in sync with `slides.md`.