pptx-to-md — Claude Code skill: PPTX to Markdown converter
pptx-to-md turns PPTX into per-slide Markdown files, preserving text, image positions, and descriptions of diagrams and screenshots. Useful when you need structured deck content with interpreted visuals.
Apache-2.0 ★ 173 updated 2026-10-24
npx skills add sammcj/agentic-coding --skill pptx-to-md -a claude-codeWhat pptx-to-md does
The skill runs a four-step pipeline: prepare.py unpacks the PPTX, renders each slide to JPG via LibreOffice, extracts embedded PNGs, and writes manifests. You dispatch one sub-agent per slide — it reads the manifest, render, and images, writes one Markdown file. Finally concatenate.py stitches everything into deck.md. Sub-agents are independent and parallelise cleanly.
Run prepare.py outside a sandbox — LibreOffice headless writes a user profile, sandboxing blocks it. In Claude Code, pass dangerouslyDisableSandbox: true to the Bash tool. Symptom: rendered/ stays empty, no deck_index.json, soffice idles at zero CPU. Hidden slides are excluded by default; pass --include-hidden to render them. For text-only decks or PDFs, the skill suggests trying uvx 'markitdown[all]' <file> -o output.md first.
What it helps with
- convert a presentation with diagrams to Markdown with each image described
- extract PPTX content into structured format for downstream processing
- keep text and screenshot positions intact during conversion
- parallelise a large deck by dispatching sub-agents per slide
- filter out hidden slides or include them in output
Example prompts for the agent
- Turn
quarterly_report.pptxinto Markdown, one file per slide, describe the images - Run the
pptx-to-mdpipeline onpitch_deck.pptx, skip hidden slides - Try
markitdownonslides.pptxfirst, if it's not enough run the full skill pipeline
How to install pptx-to-md
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill pptx-to-md -a claude-code2Manually: put the files in place
~/.claude/skills/pptx-to-md/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pptx-to-md/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill pptx-to-md -a codex2Manually: put the files in place
.agents/skills/pptx-to-md/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill pptx-to-md -a cursor2Manually: put the files in place
.cursor/skills/pptx-to-md/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sammcj/agentic-coding Skills/pptx-to-md/SKILL.md2Manually: put the files in place
.github/skills/pptx-to-md/SKILL.md1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill pptx-to-md -a gemini-cli2Platform CLI
gemini skills install https://github.com/sammcj/agentic-coding --path Skills/pptx-to-mdManually: put the files in place
.devin/skills/pptx-to-md/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pptx-to-md
How to install pptx-to-md in Claude Code?
Run npx skills add sammcj/agentic-coding --skill pptx-to-md -a claude-code, then check ~/.claude/skills/pptx-to-md/SKILL.md.
What does pptx-to-md do?
The skill converts PPTX to one Markdown file per slide: renders slides to JPG, launches a sub-agent for each to describe images and preserve text positions, then concatenates the output into a single document.
Why does prepare.py not create rendered/ and deck_index.json?
LibreOffice headless gets blocked by sandboxing: in Claude Code, add dangerouslyDisableSandbox: true when calling the Bash tool. Without it soffice runs but renders nothing.
Source text
SKILL.md · Apache-2.0
---
name: pptx-to-md
description: Convert a PPTX slide deck into per-slide markdown that preserves both the verbatim text and the meaning of embedded screenshots, diagrams and charts in their original layout positions. Use this skill (over pptx or liteparse) whenever the deliverable is markdown of a deck's content including interpreted visuals.
---
# 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.
## Step 4 - concatenate
```
python <skill>/scripts/concatenate.py <workspace-dir> [--out deck.md] [--title "Deck title"]
```
This stitches the per-slide markdown into a single `deck.md` in source-slide order with a header noting any hidden slides that were excluded. It refuses to run if any expected slide markdown is missing, which is the right behaviour - a partial deck is rarely what's wanted.
## Gotchas
**LibreOffice's PDF export skips hidden slides by default.** This means the rendered JPG index drifts from the source slide number. `prepare.py` builds a `src_to_render` map and copies each rendered JPG to a stable `slide_images/slideNN.jpg` path keyed by source slide number, so manifests reference a stable name. If you regenerate the renders later, rerun `prepare.py` so the mapping stays fresh.
**Speaker notes mapping is not always 1:1.** This skill reads the slide-to-notesSlide relationship from the slide's `_rels` file rather than assuming `slideN.xml` maps to `notesSlideN.xml`. Most decks happen to be 1:1 but it isn't guaranteed.
**Source XML can have typos.** The pipeline preserves them verbatim. Correct them in a later content-uplift pass, not during extraction - this keeps extraction deterministic.
**Hidden slides are excluded by default.** Most decks contain hidden slides for a reason (work-in-progress, deprecated content, internal-only notes). Pass `--include-hidden` only when you want them in the output - the script then renders them properly via LibreOffice's `ExportHiddenSlides` filter, so they get real JPGs in the manifests.
**Dense screenshots benefit from higher DPI.** The default is 150 DPI. For decks where text inside screenshots needs to be readable in the rendered JPG, pass `--dpi 200` or `--dpi 250` to `prepare.py`.
## Dependencies
- LibreOffice (`soffice`) on PATH
- Poppler (`pdftoppm`) on PATH
- Python 3.10+
The prepare script checks for both binaries and exits early with a clear error if either is missing.
© sammcj · Apache-2.0 · sammcj/agentic-coding