/deck-ai

name: deck-ai
user-invocable: false
description: Generate modern presentation decks (PDF) from markdown content. Local open-source alternative to Gamma — uses Slidev for layouts and Unsplash for imagery. Invoke when the user asks to "make a deck", "build slides from this", or "turn this into a presentation".

deck-ai

Turn plain markdown into a themed, image-rich slide deck exported as PDF. Closest open-source equivalent to Gamma. Runs locally. No subscription.

What this skill does

1. Reads source markdown (slides separated by `---`). 2. Picks a layout + image keyword per slide. Two modes:

• **LLM mode** (preferred): Claude writes `decisions.json` directly using the Write tool. No extra API call.
• **Rules mode** (fallback): deterministic regex picks. Used when the skill is invoked from a non-LLM harness.

3. Fetches images from Unsplash by keyword. 4. Renders the whole thing to PDF via Slidev.

When to invoke

Triggers: "make a deck", "turn this into slides", "slide version of X", "build a presentation from this", "gamma-style deck".

Do NOT invoke for plain editing / rewriting of existing slide content. Do NOT invoke if the user wants a PPTX specifically (use `python-pptx` instead).

Required setup (first run)

Prerequisites

• Node 18+ and `pnpm` on the user's machine. If missing:

  brew install node
  npm install -g pnpm

API key

• **Unsplash** (required): https://unsplash.com/oauth/applications — only the **Access Key**.
• Key lives in `.env` at the calling instance root:

  echo 'UNSPLASH_ACCESS_KEY=<your-key>' >> ./.env

• Never commit `.env`. Never paste the key into any file in this skill.
• No separate Anthropic key needed — when this skill runs inside Claude Code, Claude itself writes `decisions.json`.

Install workspace (one-time per instance)

bash <skill>/scripts/setup.sh ./deck-workspace

This creates a local Slidev workspace with themes installed. Takes ~1-2 minutes first run. Subsequent runs reuse it.

Workflow (per deck)

# 1. Preflight: key + deps must be present
bash <skill>/scripts/check_env.sh ./deck-workspace

# 2. (LLM mode) Claude reads <input.md>, decides layout + image keyword
#    per slide, and WRITES ./deck-workspace/decisions.json with the Write
#    tool (schema below). Skip this step when running outside Claude.

# 3. Generate Slidev markdown from source
#    LLM mode:
python3 <skill>/scripts/generate.py <input.md> ./deck-workspace/slides.raw.md \
    --theme seriph --decisions ./deck-workspace/decisions.json
#    Rules mode (no decisions file):
python3 <skill>/scripts/generate.py <input.md> ./deck-workspace/slides.raw.md --theme seriph

# 4. Fill image placeholders from Unsplash
python3 <skill>/scripts/fetch_images.py ./deck-workspace/slides.raw.md

# 5. Export PDF
bash <skill>/scripts/render.sh ./deck-workspace ./deck-workspace/slides.raw.md ./deck.pdf

decisions.json schema (step 2)

One object per slide, in source order. `generate.py` validates this file and exits non-zero on any violation.

[
  {"layout": "cover",       "image_keyword": "sunrise mountains"},
  {"layout": "image-right", "image_keyword": "student classroom"},
  {"layout": "center",      "image_keyword": null},
  {"layout": "end",         "image_keyword": null}
]

Rules Claude must follow when writing `decisions.json`:

• `layout` is one of: `cover`, `center`, `statement`, `two-cols`, `image-right`, `image-left`, `quote`, `end`, `default`.
• Slide 1 must be `cover`.
• If a slide has `<!-- layout: X -->` in the source, use that layout.
• `image_keyword` is 1-3 concrete nouns suitable for stock photo search. Required for `cover`, `image-right`, `image-left`. `null` for every other layout.
• No brand names, no anime character names, no abstract concepts. Use the underlying physical scene instead.

Good keywords: `library books`, `koi fish`, `child drawing`, `mountain sunrise`. Bad keywords: `Naruto`, `loneliness`, `theme of courage`, `The Ordinary World`.

Source markdown format

Slides separated by a line containing only `---`. First slide is the cover.

Example:

# Deck Title

Subtitle line.

---

# Second slide

Body content here.

<!-- layout: image-right -->

Anime anchor: Naruto.

---

# Homework

Optional closing text.

Layouts

See `references/layout-catalog.md` for the full enum and pick rules. Force a layout by adding `<!-- layout: <name> -->` in a slide body.

Image keywords

Use concrete nouns in `{{IMG:keyword}}` placeholders. 1-3 words. Good: `mountain sunrise`, `library books`, `child drawing`. Bad: `feeling of wonder`, `theme of courage` (abstract concepts return weak results).

Themes

Default: `@slidev/theme-seriph` (clean serif, modern). Fallback: `@slidev/theme-default` (sans-serif, minimal).

Install more themes in the workspace:

cd ./deck-workspace && pnpm add @slidev/theme-<name>

Browse: https://sli.dev/resources/theme-gallery

Limitations

• Slidev renders via Playwright Chromium on first export (adds ~30s).
• Unsplash free tier: 50 requests/hour. Reuse keywords if hitting the limit.
• PDF export does not preserve interactive elements (embeds, live code).
• Slide source must be standard markdown. HTML-heavy content may break layout.

Troubleshooting

| Symptom | Fix | |---|---| | `pnpm: command not found` | `npm install -g pnpm` | | `UNSPLASH_ACCESS_KEY not set` | Add to `.env` at calling dir | | Images all say "no image found" | Keywords too abstract. Use concrete nouns. | | PDF export hangs | First run downloads Chromium. Let it finish. | | Layout looks wrong | Check `<!-- layout: X -->` hint or let rules pick |

What this skill does NOT do (v2)

• AI-generated images (Unsplash stock only; could add Flux/Ideogram later)
• Brand theme editor (use provided themes or install more via pnpm)
• Per-slide image retries (one Unsplash result per keyword; no ranking)