pptx-generate-slide-skill
Fill a PowerPoint template with structured JSON via python-pptx Slide Master layouts. Not for presentations from scratch.
SKILL.mdskills/pptx-generate-slide-skill/SKILL.md
GitHubWhat I do
Pipeline contract: fill user-supplied templates — never build a deck from scratch. I render a JSON slide_data_list into a .pptx via scripts/ppt_builder.py; I am the only approved method for generating presentations from structured data.
- Validate every deck against JSON schemas (two-layer LLM-JSON repair) before rendering
- Resolve resource placeholders into real assets before rendering; embed native editable charts and native embedded pictures (never linked, never chart-as-image)
- Introspect ANY
.pptx, match layouts by placeholder-composition fingerprint - Write speaker notes (user's prompt language) to each slide's Notes pane
NOT for: decks with no template, raw OOXML editing, thumbnails/visual analysis.
Template contract
| File | Role |
|---|---|
template/default.pptx |
bundled default — used when no template_path given |
template/default.config.json |
optional layout-name pins (<slide_type>_layout) |
template/default.pptx.contract.json |
auto-generated introspection contract (mtime-cached, gitignored) |
- User-supplied template = path pass-through:
--template /path/to/user.pptx; never overwrite the default. The engine introspects it before every render. - Severe template problems abort (TemplateError): corrupt / not a PPTX / no slide master / zero layouts / serves none of the 8 slide types. Minor issues (missing fonts, no header/footer, small content area) stay non-fatal warnings.
- Capability check before authoring:
servable_slide_types(get_render_contract(tpl))— author only slide types the template actually serves; downshift density toconcisewhen a content area is< ~30 in².
Layout resolution — the gotchas that bite
Layouts resolve by placeholder-composition fingerprint, NOT by index — reordering layouts in the master must never break a deck. Layout names are only a tie-breaker/fallback, never the primary key (user templates rename layouts freely). Precedence:
default.config.jsonpin — explicit layout name, highest precedence- Fingerprint match — composition-closest layout (the template-agnostic path)
- Name-based fallback (
_LAYOUT_NAME_MAP) — backward-compat safety net - Degradation — skip slide + clear warning (never silent)
Among compatible layouts: name affinity → fewest surplus placeholders → largest content_area_in2 → index.
Slide data format
Language: multilingual (relaxed). Slide content and notes MAY be in any language — match the user's prompt language; do NOT force-translate. Notes MUST preserve the original user message verbatim and append a suggested transition.
8 slide types: title_slide, content_slide, section_header_slide, two_content_slide, comparison_slide, content_image_slide, chart_slide, closing_slide.
| Field | Req | Applies to | Notes |
|---|---|---|---|
slide_type, title |
yes | all | — |
subtitle |
no | title/closing | omit on closing_slide — the End layout's built-in sign-off shows by default |
body |
no | content/content_image | \n = new paragraph; format **Title** — Description |
body_left / body_right |
no | two_content/comparison | same body format |
chart_type, categories, series |
yes | chart | 9 chart types — table in reference.md |
chart_options |
no | chart | styling overrides — table in reference.md |
image_path |
no | any slide | embeds a native picture; PICTURE placeholder filled when present |
image_position |
no | with image_path |
full (default below-title), half-left, half-right |
image_size |
no | with image_path |
{"width": in, "height": in} override |
data_query (+ data_hint) |
no | chart | resource placeholder — resolver fills categories/series |
notes |
yes | all | full presenter script ~120–180 words (style guide below) |
presenter_name / presenter_email |
no | closing | omit on first generation; set only when user picks "Add sign-off" in Stage-5 refinement |
Body parsing: each line splits at the first —, -, or : into a bold title run + description run; ** stripped automatically; no card-slot limit.
Full field reference, chart-type/chart-options/theme tables, and example JSON: reference.md.
Resource resolution pipeline
agent emits placeholders -> resolve_slide_data_list() -> schema validation -> generate_ppt_from_data()
- Emit placeholders, never fabricated URLs or chart numbers — the agent never touches real URLs
data_querycontract: the resolver makes NO network calls; real numbers come from the agent'swebfetchpre-flight written as concretecategories/series. Fabricating chart numbers to pass validation is forbidden — every value must trace to a fetched source (citation lands in notes)- Concrete values always win — resolver never overwrites an existing
image_path/series - Non-fatal: unconfigured provider or failed fetch → warning, slide renders without the asset
- Config: copy
scripts/resolver.config.example.json→scripts/resolver.config.json(gitignored)
Schema validation
validate_slide_data_list(data, strict=True, density_mode=…) — structured errors (slide index + field path + reason) so the agent can self-correct.
- Strict mode: missing
notesand schema violations block rendering (agent pre-flight gate) - Density mode (
'standard'|'concise'|'text-heavy'|None): per-slide word-budget check → warnings only, never blocks, never promoted by strict - Default mode: degrade gracefully (skip unknown slide types, default bad
chart_typetobar, skip dataless charts); abort only on unrecoverable breakage (e.g. not an array) with a clearValidationError - Two-layer retry:
parse_and_validate(raw_text)repairs common LLM-JSON mistakes (code fences, trailing commas, single quotes, variable assignments) before validating
Invocation snippets: reference.md.
Density modes
Deck-wide per-slide visible-text budget — the primary lever against text overflow.
| Mode | Words/slide | Use when |
|---|---|---|
concise |
0–10 | image-only/keynote/hero decks; small content areas |
standard ⭐ default |
30–50 | balanced reporting decks |
text-heavy |
75–150 | dense self-study/handout decks |
Counts visible text only (title+subtitle+body+body_left+body_right; emphasis markers and —/-/: delimiters stripped; each CJK char = 1 word). Not counted: notes, chart categories/series. Underflow on title/section/closing slides is expected and harmless; out-of-budget = warning, never error. Default standard for first generation (auto-downshifted concise for small content areas; a user-stated density intent wins); adjustable post-generation in Stage 5.
Generation workflow
- Outline → self-critique → detail+JSON, schema-validated at each JSON stage. The primary agent does NOT pause after the outline — first generation is autonomous (self-critique, no pre-generation prompt); refinements are offered after the file is returned. Subagents skip the refinement prompt too. Details:
docs/DESIGN-multi-stage-generation.md. - Slide-count convention: "N pages" = TOTAL deck including cover and closing (N ≥ 3 → 1 cover + N−2 content + 1 closing; N = 2 → cover + 1 content; N = 1 → cover only). Closing defaults to
"Thank You"title, nosubtitleauthored. - Temp cleanup: outline artifacts (namespaced system temp dir) cleared automatically after every successful render (
cleanup_temp=True) — nothing pollutes the repo. - Post-generation (primary agent only): one multi-select refinement question (density ±, slides ±, add sign-off, change ratio, no adjustment) — never a second prompt.
Render
# default template
python ppt_builder.py --output report.pptx --data slides.json
# user template (path pass-through) · optional aspect ratio
python ppt_builder.py --template ~/my_company_template.pptx --output report.pptx --data slides.json --target-size 4:3
Multi-aspect-ratio output (US-4.6): target_size accepts a preset ("16:9", "4:3", "1:1") or {"width_in": W, "height_in": H}; every element scales proportionally. No-op when the target ratio equals native. Hidden-JSON-schema embed rule: the output's embedded schema slide_dimensions is rewritten to the target size — the deck is self-describing and re-usable as a target-sized template; a stale input-embedded schema is never laundered in. The <output>.render.json sidecar records aspect_ratio + scale factors.
Verification before handoff: check servable slide types up front (capability check above); after rendering, read 2–3 notes from the newest output/*.pptx to confirm house style (bundled default has 0 slides — snippets in reference.md).
Output path: <project_root>/output/, function returns the absolute .pptx path.
Error handling — rule of thumb
Fatal (clear exception): non-array input, strict-mode schema violations, missing template, TemplateError. Everything else degrades with a logged warning — unknown slide type, missing placeholder, failed slide, unknown chart_type (→ bar), missing chart data, bad image_path, unknown image_position (→ below-title), resolver failure. Full table: reference.md.
Speaker notes style — four-part structure
Every notes field = a full presenter script (~120–180 words), NOT bullet summaries:
- KEY MESSAGE — one crisp declarative takeaway
- Verbatim dialogue + stage directions — quoted speakable sentences tied to the slide's real numbers/names, interspersed imperatives (
Pause. Let the number land.); cover/closing open with[morning/afternoon]and[Name]; 2–4 quote blocks - TRANSITION — one quoted line bridging to the next slide
- COACHING — MUST include (a) tone/pacing note AND (b) an anticipated Q&A ("be ready for…")
GOOD example block: reference.md.
Self-critique rubric
Revise the outline against these before writing JSON: consistency (one coherent story) · flow (each slide sets up the next) · coverage gaps · redundancy · length (right count for the ask) · template fit (small content area → concise budget; only servable slide types).
Removed 2026-09: chart-type/options/theme tables, placement-preset details, example interaction transcripts, end-to-end deck examples, execution/introspection code dumps, and the error-handling table — moved to reference.md or deleted.