template-ingest

name	template_ingest
description	Convert a PPTX template into a structured visual slide-template asset library. Use this skill when the user wants to ingest, classify, render, or prepare PowerPoint templates for later AI slide generation.

template_ingest

Skill Purpose

This skill converts a PowerPoint (.pptx) template into a structured slide-template asset library. The Python ingest script initializes directories, renders every slide to images, and creates a base template.json. Classification, image copying, and manifest enrichment are performed by an agent or VLM following this skill — not by the Python scripts.

Inputs

• Source PPTX: A .pptx PowerPoint template file.
• Output directory: Where the template asset library will be created (e.g. data/templates/ppt_template_01).
• Template ID: Unique identifier (e.g. ppt_template_01).

Output Folder Structure

After ingest, the output directory looks like:

ppt_template_01/
├── raw_slides/
│   ├── slide_001.jpg
│   ├── slide_002.jpg
│   └── ...
├── title/
├── image_text/
├── timeline/
├── people/
├── relationship/
│   ├── relation_1/
│   ├── relation_2/
│   └── relation_3/
├── section_divider/
├── chart/
├── quote/
├── ending/
├── misc/
└── template.json

• raw_slides/ holds all rendered slide images from the PPTX.
• Category folders are empty after ingest; the agent copies classified images into them.
• template.json starts with an empty pages array.

Fixed Page Categories

Only these top-level type values are allowed:

type	notes
title	Cover / title slides
image_text	Image + text layouts
timeline	Timeline / process flows
people	Team / speaker / profile slides
relationship	Relationship / diagram slides; use subtype
section_divider	Section breaks
chart	Chart / data visualization layouts
quote	Quote / testimonial slides
ending	Closing / thank-you slides
misc	Slides that do not fit other categories

For relationship pages, set subtype to one of:

• relation_1
• relation_2
• relation_3

All other types must use subtype: "".

Workflow

Step 1 — Initialize and render raw slides

Run the ingest CLI once:

python scripts/ingest_template.py \
  --pptx demo_template.pptx \
  --output-dir data/templates/ppt_template_01 \
  --template-id ppt_template_01

This creates the directory tree, writes a base template.json, and renders all slides into raw_slides/.

Step 2 — Inspect raw slides with VLM

Open each image in raw_slides/ and analyze layout, visual style, and content suitability.

Step 3 — Classify and copy images

For each slide:

1. Choose the correct type (and subtype if relationship).
2. Copy the image from raw_slides/ into the matching category folder.
3. Rename using a descriptive filename (e.g. title/title_001.jpg).

Do not delete originals in raw_slides/.

Step 4 — Fill template.json

Add one page object per classified slide to the pages array. See references/template_json_schema.md for the exact schema.

Example page entry:

{
  "page_id": "ppt_template_01/title/title_001",
  "path": "title/title_001.jpg",
  "source_slide": "raw_slides/slide_001.jpg",
  "type": "title",
  "subtype": "",
  "description": "A detailed but concise English description of the slide. It should describe the visual style, layout, suitable content, text capacity, and what should be avoided."
}

Step 5 — Quality checks

Before finishing, verify:

• Every path and source_slide references an existing file.
• Every type is from the fixed category list.
• subtype is only set for relationship pages.
• No extra fields were added to page objects.
• raw_slides/ originals are intact.

Description Writing Requirements

The description field is the primary information carrier. Each description must mention:

• Visual style — colors, typography, mood, design language
• Layout structure — element placement, columns, hierarchy
• Suitable content — what kind of text, images, or data fits well
• Text capacity — approximate headline/body length limits
• What should be avoided — overcrowding, wrong content types, style clashes

Do not split this information into separate fields such as layout, style, slots, or negative_constraints.

Prohibited Actions

• Do not create categories outside the fixed category list.
• Do not add extra fields to page objects in template.json.
• Do not reference image paths that do not exist.
• Do not delete original images in raw_slides/.
• Do not split description into dense fields such as layout, style, slots, or negative_constraints.
• Do not run automatic VLM classification inside the Python scripts.

Final Output Summary Format

When classification is complete, report:

Template classification completed.

Template ID: ppt_template_01
Raw slide count: 12
Classified page count: 12

Count by category:
  title: 1
  image_text: 3
  timeline: 1
  people: 1
  relationship: 2
  section_divider: 1
  chart: 1
  quote: 0
  ending: 1
  misc: 1

Pages placed in misc:
  - slide_011.jpg: No clear category match; complex multi-panel layout.