# Keynote Deck

> Generate native Keynote (.key) presentations from markdown, using the user's branded Keynote template. Use when asked to create Keynote slides, a slide deck, or a presentation from markdown or an outline. Renders via md2key + AppleScript for zero-loss native Keynote output — no PowerPoint conversion step.

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

---


# Keynote Deck Generator

Turns markdown into a **native .key file** by pouring content into a branded
Keynote template. The model's job is CONTENT ONLY — structure, wording, speaker
notes. All visual design lives in the Keynote template's master slides, so
never attempt layout, colors, or fonts here.

## Pipeline

```
deck.md ──▶ scripts/generate.sh ──▶ Keynote (AppleScript/md2key) ──▶ deck.key + preview PNGs
```

Run: `~/.claude/skills/keynote-deck/scripts/generate.sh <markdown-file> [output.key]`

The script pins the Homebrew Ruby and md2key paths, launches Keynote by bundle
id (`com.apple.Keynote`), opens a copy of the user's template, converts, saves,
and exports preview PNGs next to the output.

## Workflow

1. **Locate or author the markdown.** If given a file, use it. If given a
   topic/outline, author the deck markdown first (see Authoring rules) and
   show it to the user before generating.
2. **Generate:** run `generate.sh deck.md output.key`.
3. **Verify — never skip.** Read 2–3 of the exported preview PNGs (cover, a
   code slide, the densest bullet slide). Check for: text overflowing its box,
   code wider than its panel, tables too tall, orphaned single-word bullet
   wraps. If found, tighten the markdown (shorter bullets, split slide, trim
   code) and regenerate. One regeneration pass is normal.
4. Report the .key path. The document is left open in Keynote for hand-tweaks.

## Authoring rules

Structure:
- `# Title` — first heading becomes the cover slide; the line(s) after it
  become the cover body (subtitle).
- One heading per slide. One idea per slide.
- `^ note text` — presenter note. **Every content slide gets one**: 2–4
  conversational sentences the presenter can speak. For course/video decks
  this doubles as the narration script.
- `---` separators are optional; headings define slides.

Heading level → master slide (the template names its masters `cover`, `h1`–`h5`):

| Markdown | Master | Suggested role |
|----------|--------|----------------|
| `#` (first) | `cover` | cover slide |
| `#` (mid-deck) | `h1` | section divider |
| `##` | `h2` | content — light |
| `###` | `h3` | code — dark |
| `####` | `h4` | content — dark |
| `#####` | `h5` | code — light |

The light/dark pairing is the recommended convention (decks can run all-light,
all-dark, or alternating) — but the template owner decides what each master
looks like; follow whatever their template does.

Density limits (Keynote boxes don't auto-shrink — overflow is the #1 failure):
- ≤ 5 bullets per slide, ≤ 8 words per bullet, ≤ 1 nesting level.
- Code blocks: ≤ 12 lines, ≤ 60 columns. Longer code → split across slides
  ("part 1 / part 2") or trim to the teaching-relevant lines with `# ...`.
- Tables: ≤ 4 columns, ≤ 5 rows.
- No inline bold/italic/links — md2key pastes plain text; styling comes from
  masters. Write so emphasis isn't needed.

Supported content per slide (title + ONE of these works best):
- Bullet list (with one nesting level)
- Fenced code block — syntax-highlighted via `highlight` (dark panel)
- Markdown table
- Image: `![](absolute/or/relative/path.png)`
- ` ```mermaid ` block — rendered to a diagram (requires `mmdc`; if missing,
  pre-render to PNG and use an image instead)

Deck conventions:
- Open with a cover (`# Deck Title` + subtitle line).
- Second slide: agenda or "What you'll learn" — 3–5 bullets.
- Close with a recap/summary slide.
- Prefer many light slides over few dense ones — slides are glanceable
  signposts, not documents.

## Template

Template resolution order (generate.sh handles this):
1. `$KEYNOTE_DECK_TEMPLATE` env var
2. `./keynote-template.key` in the current project
3. `~/.claude/skills/keynote-deck/templates/default.key`
4. Fallback: stock "White" theme (warn the user output is unbranded)

The template is a normal .key file whose **master slides are named** `cover`,
`h1`–`h5` (lowercase, exact). If the user has no template yet, offer to help
them build one — the full method (designing background art with Claude,
rendering it, assembling masters) is in `TEMPLATE-GUIDE.md` in this skill's
directory. Design changes belong in the template's masters, never compensate
for design issues in markdown.

## Requirements & troubleshooting

- Deps: Homebrew Ruby, `md2key` gem, `highlight` (brew). generate.sh checks
  and prints install commands if missing.
- Keynote must be allowed Automation permission for the shell (macOS prompts
  on first run — user must click Allow).
- md2key drives the **front document**; tell the user not to click around
  Keynote mid-generation.
- Code slides: generate.sh auto-patches md2key (idempotently) to use this
  skill's 1740×800 code panel at position {90, 170}, and snaps pasted code
  text to {154, 226}. Only text items below y200 are moved — Keynote counts
  the title placeholder among "text items" and it must never be repositioned.
- Masters used for code slides should have **no body placeholder** — an
  unfilled placeholder exports its prompt text onto the slide.
- If AppleScript errors after a macOS/Keynote update, offer the official pptx
  skill route (.pptx opens in Keynote with minor fidelity loss) as a fallback.