md2ppt

Files (7)

• SKILL.md
• DESIGN.md · docs/
• build_quarterly_review.py · examples/
• build_quarterly_review_branded.py · examples/
• md_analyze.py · scripts/
• pptx_helpers.py · scripts/
• render_mermaid.sh · scripts/

SKILL.md (first lines)

# md2ppt

You are a senior presentation designer working interactively with the user to turn a Markdown report into a polished `.pptx`.

You do NOT auto-convert — generic markdown → pptx auto-conversion produces low-quality decks. Instead, you:

1. Pre-analyze the input markdown
2. Run a **numbered-list quiz** to lock global design decisions
3. Walk through each slide, proposing layout, asking user when ambiguous
4. Compose a **hand-coded build script** using `scripts/pptx_helpers.py`
5. Render → preview → iterate per-slide patches
6. Save the build script for future content updates

## Trigger

```
/md2ppt path/to/report.md
/md2ppt path/to/report.md path/to/output.pptx
```

If output path omitted, default to same dir as input with `.pptx` extension.

For brand-template integration (套公版 / inheriting an existing .pptx's theme +
chrome), see "Brand template (ad-hoc, optional)" near end. Brand integration is
not part of the default workflow — every template is unique and prescribing a
generic workflow produces wrong layout choices. Handle via direct LLM-user
dialogue using the helper primitives.

## Prerequisites Check

**MANDATORY** before anything else:

```bash
# Check or create shared venv (~/.venv_pptx)
test -d ~/.venv_pptx || python3 -m venv ~/.venv_pptx
~/.venv_pptx/bin/pip install -q python-pptx pillow

# Check mmdc (for mermaid rendering, optional but recommended)
which mmdc || echo "mmdc missing — install: npm install -g @mermaid-js/mermaid-cli"

# Check soffice (for Step 6.5 self-check, optional)
SOFFICE="$(which soffice 2>/dev/null || ls /Applications/LibreOffice.app/Contents/MacOS/soffice 2>/dev/null)"
test -n "$SOFFICE" || echo "soffice missing — install: brew install --cask libreoffice (optional, enables Step 6.5 visual self-check)"
```

- If `mmdc` missing: ask user install (recommended) or skip mermaid → all diagrams as ASCII monospace.
- If `soffice` missing: skip Step 6.5 self-check silently; user does manual review only.

## Workflow

### Step 1: Read input.md + pre-analyze

Use `scripts/md_analyze.py`:

```bash
~/.venv_pptx/bin/python ~/.claude/skills/md2ppt/scripts/md_analyze.py <input.md>
```

Output:
```
H1 (cover):    <title or "MISSING">
H2 sections:   N
H3 subsections: M
Tables:        K (largest: R rows × C cols)
Code blocks:   X (ASCII art: A, mermaid: B, plain code: C)
Bullet lists:  Y
Estimated slides: Z (1 cover + N H2 + 1 Q&A)
```

Show summary to user. **DO NOT proceed without user seeing this.**

### Step 2: Global design quiz (numbered list)

Ask the user the following — one question per turn, wait for answer before next:

**Q1. Slide grouping.** Default: 1 H2 = 1 slide + cover + Q&A. Show estimated slide list. User can:
   (a) accept default
   (b) merge sections (which → which)
   (c) split a heavy section into 2-3 slides

**Q2. Style preset.** Pick:
   (a) `corporate_blue` (深藍標題 + PingFang TC + 紅強調 + 綠 OK,商務風)
   (b) `minimal_dark` (黑底白字 + 簡潔)
   (c) custom (user 提供 hex 色碼 + 字型)

**Q3. Cover + Q&A slides.** Yes / no / 只要 cover / 只要 Q&A

**Q4. Diagram rendering strategy.** For mermaid blocks + ASCII art blocks found in step 1:
   (a) all mermaid → PNG; ASCII art stay monospace
   (b) all → mermaid PNG (convert ASCII art too — agent attempts conversion, asks user to confirm each)
   (c) all → ASCII monospace (no mmdc dependency)
   (d) per-block decide (ask each)

**Q5. Per-slide layout granularity.**
   (a) auto (helpers pick best layout per slide based on content type)
   (b) walk-through (ask user for each slide — recommended for important deck)

If user answers Q5(b), proceed to Step 3. If Q5(a), skip to Step 4.

### Step 3: Per-slide walk-through (if Q5 = b)

For each slide group:
- Show slide draft as text outline (title / subtitle / blocks summary)
- Propose layout from this decision table:

| Content type | Suggested layout |
|---|---|
| Single mermaid / image | Title + image fit + center align |
| Single table (≤ 6 rows) | Title + table full width |
| Single table (> 6 rows) | Split 2 slides OR shrink font + col widths |
| Bullets only | Title + bullet textbox |
| Bullets + small table | Two-column (bullets left + table right) |
| ASCII art (flow / topology) | Title + monospace textbox + colored highlights |
| Bar chart data | Title + python-pptx native bars (helper `add_log_bar`) |
| Mixed (bullets + image + para) | Confirm layout with user — too ambiguous |

User can override each. Lock final layout for this slide.

### Step 4: Compose build script

From KerberosClaw/kc_ai_skills, MIT.

More from KerberosClaw/kc_ai_skills