# Pptx Template Parsing

> Use before adapting or debugging any PPTX template-driven deck. Parses a template into a portable spec.json contract: classified shape tree, slide roles, repeated card structures, per-slide fill_plan, text style/paragraph metadata, font availability, and optional renders. This is the required first half of the parse→generate pipeline consumed by ppt-template-adaptation.

- **Type:** Skill
- **Install:** `agentstack add skill-cxyzyr-pptx-template-skills-pptx-template-parsing`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CxyZyr](https://agentstack.voostack.com/s/cxyzyr)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CxyZyr](https://github.com/CxyZyr)
- **Source:** https://github.com/CxyZyr/PPTX-Template-Skills/tree/main/skills/pptx-template-parsing

## Install

```sh
agentstack add skill-cxyzyr-pptx-template-skills-pptx-template-parsing
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PPTX Template Parsing

Turn a `.pptx` template into a semantic `spec.json` that downstream generation can fill
mechanically — without the agent ever hand-reading shape indices off the slide.

This is the **first half** of the pipeline:

```
template.pptx ─[THIS SKILL]→ spec.json (+ summary.txt + renders/*.png)
                                   │
                                   ▼
                          ppt-template-adaptation  (authors content_plan.json, fills the deck)
```

## When to use

- A user provides a PPT template that will be reused (not redesigned).
- Before any generation: generation needs the `spec.json` slot map this skill produces.
- When you need to know, per slide: what role it plays, where the title/body/cards/icons/logo/images
  live, and which slides repeat a card structure.
- When a generated deck has layout, style, overlap, or missing-slot problems. Check whether parsing
  captured the right slots and text styles before adding generation fallbacks.

## Operating rule

The parser output is the contract. Do not hand-pick PowerPoint shape indices from memory, screenshots,
or a previous failed deck. If `fill_plan` is wrong, fix parsing/classification first, rerun this skill,
then regenerate with `ppt-template-adaptation`.

## What it produces

| Output | Purpose |
|---|---|
| `spec.json` | The machine-readable contract consumed by generation. See `references/spec-schema.md`. |
| `summary.txt` | One line per slide: role + confidence + detected slots. Read this first. |
| `renders/*.png` | One PNG per slide when rendering is enabled. Use for human/visual review when allowed. |

## How to run

```bash
python3 skills/pptx-template-parsing/scripts/parse_template.py \
  --template "PPT模板/大气人工智能科技感PPT模板.pptx" \
  --out workspace/specs/ai_tech
```

Flags:
- `--no-render` — skip LibreOffice rendering (faster; do this for a quick structural pass).
- `--limit N` — only parse the first N slides (useful while iterating).
- `--dpi 110` — render resolution (default 110).

Rendering needs `libreoffice` + `pdftoppm` on PATH. If rendering fails the parser still emits
`spec.json` (renders are best-effort).

## Required workflow

1. Run `parse_template.py` against the original template, not a previously generated deck.
2. Read `summary.txt` and flag any low-confidence slide (`role_confidence < 0.5`) or unexpected slot
   count, especially `contents` and repeated-card slides.
3. Read the relevant `fill_plan` entries in `spec.json`: `title`, `labels`, `body`, `cards`,
   `images`, `charts`, `tables`, `logo`, and `visual_obstacles`.
4. For text-sensitive templates, inspect each slot's `style.paragraphs` / `title_style.paragraphs`.
   Mixed-format boxes must preserve paragraph/run style instead of being flattened during generation.
5. Check `template.theme.font_availability`. Missing fonts explain render differences, but the PPTX
   should still preserve the original font names in `style`.
6. Only after the slot map looks coherent, hand `spec.json` to `ppt-template-adaptation` and create a
   `content_plan.json`.

## Debugging checklist

- Contents page: card count must match visible directory entries. If four entries parse as one large
  card, fix card-list/group extraction here.
- Shared text boxes: if a single text box contains number/title/body with different styles, the parsed
  style must include `paragraphs` with run-level sizes/colors.
- Alignment: preserve parser values such as `CENTER`, `LEFT`, and `DISTRIBUTE`. Do not reinterpret
  WPS distributed alignment as ordinary center.
- Icon/image boundary: small semantic glyphs belong in `cards[].icon`; photos/screenshots belong in
  `images[]`.
- Chart/table pages: if native chart/table slots are present, expose them as `charts[]` / `tables[]`;
  do not treat them as ordinary text pages.

## How the classifier works (no single signal is trusted)

Each shape gets a `role`, a `role_confidence`, and the list of `signals` that fired, so its decision is
reviewable against the render. Roles are assigned in priority order — hard shape types (table/chart) →
real placeholders → stock placeholder text (`点击输入标题`) → font-size/geometry heuristics. Groups become
`card` only when they carry substantive text. Full rules: `references/classification-signals.md`.

Slide roles (cover / contents / section_divider / content / ending) and the per-slide `fill_plan` are
derived on top of the shape roles. Full rules: `references/slide-roles.md`.

## Reference read order

Read only what the task needs:

- `references/spec-schema.md` — required when consuming or debugging `spec.json`.
- `references/classification-signals.md` — read when a shape role is wrong.
- `references/slide-roles.md` — read when a slide role, card count, or `fill_plan` is wrong.

## Scripts

- `scripts/parse_template.py` — CLI entry: template → `spec.json` + `summary.txt` + renders.
- `scripts/shape_classifier.py` — per-shape role classification (builds the node tree).
- `scripts/slide_classifier.py` — slide role + card-list detection + `fill_plan` synthesis.

These scripts depend on `lib/pptx_toolkit` (shape walking, geometry, rendering).

## Accuracy expectations

This is heuristic classification, not ground truth. `role_confidence` and `signals` exist precisely so a
reviewer can catch mistakes. Always sanity-check `summary.txt` and the relevant `spec.json` entries
before authoring a `content_plan.json` against the spec. When visual review is available, compare renders
against the template; otherwise leave the render artifacts for human review and rely on structural checks.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CxyZyr](https://github.com/CxyZyr)
- **Source:** [CxyZyr/PPTX-Template-Skills](https://github.com/CxyZyr/PPTX-Template-Skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cxyzyr-pptx-template-skills-pptx-template-parsing
- Seller: https://agentstack.voostack.com/s/cxyzyr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.