deck-ai

name	deck-ai
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)