PPTX To Md

Extract PPTX to per-slide markdown

This skill turns a .pptx file into one markdown file per slide, preserving layout context and image meaning. It does not paraphrase the text or describe images out of context. The output is suitable as input to a content uplift pass, a markdown-to-HTML build, or any other downstream transform.

When to use

The deck mixes text with embedded screenshots, diagrams, charts, or code samples in a layout that matters (columns, side-by-side panels, callouts). Plain text extraction would lose either the layout or the meaning of the images.

IMPORTANT: If the deck is: a PDF, text-only or if it has no images that are meaningful to the content, uvx 'markitdown[all]' <path-to-file> -o output.md is faster and usually sufficient without going through this skill's more complex pipeline as described below. You can try this and ask the user to review the output letting them know that if it's not sufficient you will continue with the more complex slide extraction pipeline.

Pipeline

PPTX -> prepare.py -> manifests + rendered JPGs + embedded PNGs
     -> dispatch one sub-agent per slide
     -> per-slide markdown files
     -> concatenate.py -> deck.md

The orchestrator (you, in the calling session) does two things: run the prepare and concatenate scripts, and dispatch one sub-agent per visible slide. Each sub-agent does the actual vision-and-text composition for one slide and writes one markdown file. Sub-agents are independent so they parallelise cleanly.

Step 1 - prepare the workspace

python <skill>/scripts/prepare.py <pptx-path> <workspace-dir>

This unzips the PPTX, renders every visible slide to a JPG via LibreOffice and pdftoppm, then writes one manifest JSON per visible slide. After rendering, the script checks the JPG count matches the slide count and warns to stderr if they diverge - LibreOffice has been known to silently drop slides, so always read that warning before dispatching sub-agents.

Run this step OUTSIDE any command sandbox. LibreOffice headless needs to write its per-user profile and set OS/task policies that a sandbox blocks, so under sandboxing soffice fails silently: no PDF, empty output, and no deck_index.json. Under Claude Code specifically, run prepare.py with the Bash tool's dangerouslyDisableSandbox: true. Symptom to recognise: rendered/ stays empty and no deck_index.json is written while the soffice process sits at near-zero CPU.

The workspace looks like:

workspace/
  unpacked/                    raw OOXML
  rendered/                    PDF + ordered slide JPGs
  manifests/slideNN.json       per-slide manifest
  slide_images/slideNN.jpg     rendered whole-slide JPG (stable name)
  embedded_images/slideNN/     embedded PNGs grouped per slide
  slides/                      empty - sub-agents write slideNN.md here
  deck_index.json              {visible, hidden, src_to_render}

Step 2 - pilot before scaling

Pick 2-4 slides that span the deck's variety: one dense, one with screenshots, one with a custom diagram, one with sparse text. Dispatch sub-agents for those first using the prompt template at references/sub_agent_prompt.md, and compare the output against the exemplar in references/example_slide.md. Adjust the deck-specific notes in the prompt if needed (terminology to keep verbatim, terms to flag, conventions to enforce). Only then fan out to the rest of the deck.

The pilot is not optional. Per-deck variation in image style, layout density, and terminology means a prompt that works perfectly for one deck may produce bland or duplicated output on another.

Step 3 - dispatch sub-agents in parallel

For each visible slide, dispatch one fresh sub-agent (named subagent type, not a fork - the agent only needs its manifest, so a fresh context is cheaper than inheriting the orchestrator's history). Each agent reads its manifest, the rendered slide JPG, and the embedded PNGs, then writes one slideNN.md.

To get the dispatch list, run:

python <skill>/scripts/dispatch_list.py <workspace-dir>

This emits one tab-separated row per slide that still needs a sub-agent (slide_number, manifest_path, output_path), skipping slides whose markdown already exists. That makes reruns after a partial failure trivial - no slide is re-extracted unnecessarily.

Suggested batching: 6 sub-agents per wave. Larger waves work but produce more interleaved completion notifications, which is noisier without being faster. Each sub-agent typically takes 20-50 seconds.

The exact prompt to send each agent is in references/sub_agent_prompt.md. Substitute the placeholders before sending using str.replace() (not str.format() - the template contains literal braces). The prompt's rules - length-tuned image descriptions, external-links de-duplication, single-line reply - are not stylistic; they were each added after a real failure mode in earlier runs. See the prompt template for the rationale.