---
name: niki2423/pptx-to-beamer
source: https://app.decimal.ai/s/niki2423-pptx-to-beamer@1/SKILL.md
source_sha256: 71702bdb21c2
---

# PPTX to Beamer

## Overview

Use this skill to turn a `.pptx` file into a Beamer project with extracted assets and a validation pass. The bundled scripts are designed for deterministic conversion of common slide content, while the workflow leaves room for agent judgment on theme choice and hard-to-map visual elements.

## When To Use It

- The user wants a PowerPoint deck reconstructed as a LaTeX Beamer document.
- The task requires extracting text hierarchy, slide titles, bullet nesting, or embedded images from `.pptx`.
- The user wants a compilable starting point rather than manual copy/paste.
- The deck contains some complexity such as mixed formatting, tables, or decorative shapes that need fallback handling.

## Quick Start

1. Convert the deck:

```bash
python3 scripts/pptx_to_beamer.py INPUT.pptx \
  --output build/presentation.tex \
  --assets-dir build/assets \
  --theme auto
```

2. Validate the generated `.tex`:

```bash
python3 scripts/check_beamer_tex.py build/presentation.tex
```

3. If LaTeX is installed, compile as an additional verification step:

```bash
pdflatex -interaction=nonstopmode -halt-on-error -output-directory build build/presentation.tex
```

## Workflow

### 1. Gather Constraints

- Ask for a specific Beamer theme only when the user has a real preference or branding constraint.
- If the user does not specify a theme, use `--theme auto`. The converter will infer a professional default from slide density and available theme metadata.
- Preserve the deck’s slide order unless the user explicitly asks for reorganization.

### 2. Convert Deterministically First

Run `scripts/pptx_to_beamer.py` before making manual edits. It handles:

- Slide titles to `\begin{frame}{...}`
- Bullet lists and nesting to `itemize` or `enumerate`
- Inline formatting such as bold, italic, and underlined runs
- Embedded images extracted from the `.pptx` archive into a local assets directory
- Basic tables converted into `tabular`

### 3. Apply Agentic Reasoning

The converter produces a strong draft, but the agent should still inspect the result and make judgment calls:

- **Theme selection**: Prefer `metropolis` for sparse, image-forward, or modern decks. Prefer `Madrid` for denser, corporate, or text-heavy decks. Use an explicit user choice over any inferred choice.
- **Contextual formatting**: Keep inline emphasis when it clarifies meaning. If a slide uses formatting purely decoratively, simplify when needed to keep the Beamer source readable.
- **Complex shapes and diagrams**: Do not invent TikZ reconstructions unless the user asks. Instead, preserve nearby text, add a short LaTeX comment noting the omitted object, and, when possible, export the visual as an image fallback.
- **Tables**: Preserve table content and basic structure. If a table is too wide or visually intricate, wrap it in `\resizebox{\textwidth}{!}{...}` or convert it into a simpler bullet summary only if the user approves.

For mapping details and fallback rules, read [references/mapping-guide.md](references/mapping-guide.md).

### 4. Validate and Repair

Always run `scripts/check_beamer_tex.py` after generation. The validator checks:

- Unmatched `\begin{...}` and `\end{...}` pairs
- Unbalanced braces
- Missing image files referenced by `\includegraphics`
- Optional `pdflatex` or `latexmk` compilation when available

If validation fails:

- Escape invalid LaTeX characters such as `%`, `&`, `_`, `#`, `{`, and `}`.
- Fix or remove broken image references.
- Replace unsupported constructs with plain text or comments rather than leaving invalid LaTeX behind.

### 5. Verify Output Quality

Before handing off:

- Spot-check title slides, dense bullet slides, and any slide with media.
- Make sure nested bullets are represented with nested list environments.
- Confirm extracted image paths are relative to the generated `.tex` file.
- Call out any manual approximations made for diagrams, SmartArt, or decorative shapes.

## Resources

### `scripts/pptx_to_beamer.py`

Primary converter. Reads the PPTX zip package directly with Python standard library modules and writes:

- A Beamer `.tex` file
- An extracted assets directory for images
- A conversion summary on stdout

### `scripts/check_beamer_tex.py`

Validation helper for syntax, environment pairing, image references, and optional LaTeX compilation.

### `references/mapping-guide.md`

Concise mapping rules for text, lists, formatting, tables, images, and non-1:1 PowerPoint objects.

### `references/discussion-post-template.md`

Ready-to-post draft containing a summary, sample usage, and reflection. Use this when the user asks to publish or share the skill work.