Slides: Markdown in, PowerPoint out

The Markdown file is the deck. The .pptx is built from it and never edited by hand. Every change is: edit the .md → build → check → reload LibreOffice.

Resolve the skill directory first. It is the base directory Claude Code printed when this skill loaded (a symlink path is fine). Every path below written <skill-dir>/… means that directory, made absolute. The deck folder is where the deck's *-slides.md lives; pass it absolute too.

Route to one phase

Read the argument, then read all of that phase's files in one parallel turn. They're next to this file:

Files in a deck folder

Read the deck folder's CLAUDE.md before editing a deck. Its rules beat the general ones below.

The loop, after every edit

One command, not three:

<skill-dir>/scripts/loop.sh DECK_DIR/NAME-slides.md [--png DIR]

It runs build.sh (lint + pandoc → NAME.pptx), then check.py (overflow report), then reload.py (show it in LibreOffice).

• Lint errors stop the build, and nothing is reloaded. Fix the Markdown; don't work around the linter.
• Check error: means content runs off the slide; warning: means text runs past its box, which in practice is text touching the bottom edge. Fix both: cut words, split the slide, or move detail to speaker notes. To see a slide, add --png DIR (a scratch directory) and read DIR/slide-NN.png.
• A check error still reloads, so the user sees the problem slide, but loop.sh exits 1.
• To run a step on its own, use the script directly. Run check.py and reload.py with /usr/bin/python3: the uno module comes from the system LibreOffice package.

LibreOffice safety

reload.py talks to LibreOffice through a local pipe (claude_slide). It starts LibreOffice if nothing is listening, and otherwise closes and reopens only this deck's window.

• Never open the deck with xdg-open: that LibreOffice has no pipe, so later reloads can't reach it.
• If LibreOffice is running without the pipe (pgrep -a soffice shows no --accept), don't kill it; the user may have unsaved work. Ask them to close it, then run reload.py.
• check.py runs its own headless LibreOffice with a throwaway profile, so it's safe at any time.

Markdown structure

• ## makes a section title slide, ### a content slide. Never #.
• Never two title slides in a row. The front-matter title slide and every ## must be followed by a ###. The linter enforces this.
• ::: notes … ::: is speaker notes, not shown on the slide.
• An HTML comment (<!-- … -->) isn't converted. The one at the top of the deck is for the presenter: how to convert, open questions.
• Side by side: :::::: {.columns} holding two ::: {.column} blocks.
• Images live in images/. Credit every image from outside the project in that slide's notes (source and license).

Writing limits

• About 6 bullets per slide, tables of 7 rows or fewer. The linter warns past both.
• A slide says one thing. Detail the presenter needs goes in the notes, not on the slide.
• Which slides get a diagram or a photo is decided by visual-rules.md: diagrams wherever items connect, photos only in four cases.

Requirements

• pandoc on the PATH. If missing, install without sudo from the static release: curl -L https://github.com/jgm/pandoc/releases/download/<v>/pandoc-<v>-linux-amd64.tar.gz | tar xz --strip-components 2 -C ~/.local/bin pandoc-<v>/bin/pandoc
• The template's fonts, or fonts with the same letter widths, or the overflow check measures the wrong widths (check.py warns). For reference.pptx that's Calibri or Carlito: sudo apt install fonts-crosextra-carlito, or without sudo, put the four Carlito-*.ttf files from github.com/google/fonts (ofl/carlito) into ~/.local/share/fonts and run fc-cache -f.
• LibreOffice Impress with Python UNO (/usr/bin/python3 -c "import uno"), and pdftocairo (poppler-utils) for --png.
• For visuals.md: Google Chrome or Chromium for diagrams (falls back to LibreOffice, which renders fonts worse), and numpy and Pillow (/usr/bin/python3 -c "import numpy, PIL") for photo search.