Ppt Template Fill

PPT Template Fill

Run when the user provides a raw .pptx template plus new content / a new topic and asks to generate a .pptx from that template. This skill treats the existing .pptx as a native slide library and produces a new .pptx by selecting, cloning, and patching source slides.

This skill is independent from the ppt-master SVG generation pipeline. It keeps the original PowerPoint design intact and writes a new .pptx by cloning selected source slides and replacing text directly in OOXML. Executable scripts are shared with ppt-master and stay at .claude/skills/ppt-master/scripts/.

Route Entry and Authority

Entry contract: ppt-master/workflows/routing.md selects the raw-PPTX template-fill route before this full skill is loaded. Route selection does not require loading the main ppt-master/SKILL.md.

Gate owner: After selection, this skill owns every runtime gate from inputs through native render validation. Root summaries and the main SVG skill add no preflight, confirmation, spec, SVG, export, or completion gate to this route. Reusing shared scripts does not transfer workflow ownership.

Route change: If the request changes to reusable-template creation, strict 1:1 beautify, main-pipeline re-architecture, or finished-PPTX native enhancement, return to routing.md before loading the new owner.

Boundary against template-based generation: run this skill for raw PPTX template + generated PPTX requests. Skip this skill only when the user explicitly wants a reusable template package, SVG-derived template roster, or SVG-generated deck that can freely select / repeat / skip / adapt template pages. In that case, they must run create-template first and then provide the generated template directory path to the ppt-master main pipeline.

When to Run

Recognize requests that combine an existing PowerPoint template with new content or a topic and ask for a generated .pptx without explicitly requesting the reusable SVG/template-package route:

Hard rule: Do not run main-pipeline preflight.py, confirm_ui, validate_spec.py, svg_quality_checker.py, finalize_svg.py, svg_to_pptx.py, or verify_deck.py for this skill. Do not run pptx_to_svg.py or pptx_template_import.py. This skill edits PowerPoint directly and uses its own plan, apply, OfficeCLI, and native-render gates.

Deterministic routing rule: do not ask a route-choice question for raw PPTX template + generated PPTX requests; route them here. If the user asks for SVG/template-package generation from a raw PPTX, state that create-template must run first and stop this skill until they provide the generated template directory path.

Step 1: Inputs

🚧 GATE: The user has provided:

If the content material is only a topic with no supporting facts, gather or ask for source material first. Do not invent detailed factual content.

Step 2: Create the Project Workspace

Create a dedicated project directory under projects/. Do not write outputs directly into projects/ root. Reuse the standard project manager so source import rules stay consistent with the rest of the repository:

python3 .claude/skills/ppt-master/scripts/project_manager.py init "<project_name>" --format ppt169
python3 .claude/skills/ppt-master/scripts/project_manager.py import-sources "<project_dir>" "<source.pptx>" "<material...>"

Source import rule: project_manager.py import-sources copies files from outside the repository and moves repo-local files by default, unless --copy / --move is explicitly supplied. Keep this shared behavior; do not create a separate template-fill import path.

Use this fixed layout:

Hard rule: A template-fill project is a project, not a loose output file. The final answer must point to <project_dir>/exports/<name>.pptx, and all intermediate artifacts must remain inside <project_dir>.

Step 3: Extract the PPTX Intake Bundle

project_manager.py import-sources automatically runs the standard PPTX intake for imported PowerPoint files and writes <stem>.slide_library.json into <project_dir>/analysis/. If you are working from a manually assembled project that does not have the intake artifact, run the template-fill analyzer directly:

python3 .claude/skills/ppt-master/scripts/template_fill_pptx.py analyze "<project_dir>/sources/<source.pptx>" -o "<project_dir>/analysis/<stem>.slide_library.json"

Read <project_dir>/analysis/<stem>.slide_library.json (intake prefixes per-deck artifacts by the template deck's file stem) and identify:

Selection rule: Pick pages by content fitness, not by source order alone. A source page is useful only if its visible structure can carry the target message without heavy redesign.

A page's layout already encodes a rhetorical shape — a single hero statement, a lead-then-detail split, a 2×2 comparison, a stepwise progression, a metric row. Match the source material's own logic to a page whose structure expresses that same logic; do not pour unrelated content into a slot just because it is empty. When no selected page fits a piece of content well, drop that page or that content rather than forcing it — a forced fill reads as stiff. It is fine to use fewer pages than the source deck has.

Layout-first planning: Treat <stem>.slide_library.json as a layout inventory, not as an ordered deck outline. Before writing fill_plan.json, infer each reusable source page's affordance from JSON fields:

SmartArt boundary: A selected source slide keeps its original native SmartArt parts. check-plan warns because the fill plan cannot replace SmartArt node text; choose another layout unless the original diagram content is intentionally retained, or explicitly accept the warning.

Hard rule: The target story controls output order. Source slides may move forward, move backward, be omitted, or be reused several times when their layout matches multiple target messages. Never treat source slide order as a default outline unless the user explicitly asks to preserve it.

Required mapping pass: Record a concise page-to-layout rationale in each planned slide before finalizing the plan. Use the per-slide layout_rationale object in fill_plan.json with layout_pattern, why_fit, and risk. This is human-review evidence that selection came from template structure rather than sequential replacement; it is not a mechanical checker gate.

Step 4: Build the Fill Plan

Create a scaffold:

python3 .claude/skills/ppt-master/scripts/template_fill_pptx.py scaffold "<project_dir>/analysis/<stem>.slide_library.json" -o "<project_dir>/analysis/fill_plan.json" --slides "1,3,4"

Then edit <project_dir>/analysis/fill_plan.json by hand from the source material. The plan is the single execution contract.

Pages are reusable: the output is the ordered slides list, not a one-to-one copy of the source deck. A source page is not single-use — list the same source_slide as many times as you need, each entry with its own replacements, to drive several output slides from one good layout (e.g., reuse a single content layout for five content pages). Likewise you may omit source pages entirely and put the selected ones in any order.

Scaffold boundary: scaffold --slides is only a convenience starter. If the final plan needs repeated source pages or a story order that differs from the template order, duplicate / reorder entries in fill_plan.json manually or generate the plan from <stem>.slide_library.json; do not let scaffold output constrain the deck structure.

The plan structure:

{
  "schema": "template_fill_pptx_plan.v1",
  "status": "draft",
  "source_pptx": "projects/source.pptx",
  "accepted_warnings": [
    {
      "plan_slide": 3,
      "slot_id": "s03_sh5",
      "code": "text_capacity",
      "reason": "User accepted dense wording"
    }
  ],
  "slides": [
    {
      "source_slide": 1,
      "purpose": "cover",
      "layout_rationale": {
        "layout_pattern": "hero cover",
        "why_fit": "Large title and subtitle slots fit the opening message without redesign.",
        "risk": "Subtitle must stay short."
      },
      "notes": "Speaker notes for this filled slide.",
      "transition": "fade",
      "replacements": [
        {
          "slot_id": "s01_sh4",
          "text": "New title"
        }
      ],
      "table_edits": [
        {
          "table_id": "s01_tbl3",
          "cells": [
            {"row": 0, "col": 0, "text": "Metric"},
            {"row": 0, "col": 1, "text": "Value"}
          ]
        }
      ],
      "chart_edits": [
        {
          "chart_id": "s01_ch4",
          "categories": ["A", "B"],
          "series": [
            {"name": "Series 1", "values": [10, 20]}
          ]
        }
      ]
    }
  ]
}

Per-slide plan discipline:

Fit check before apply:

• Cover pages: replace title / subtitle / author only.
• Chapter pages: use short section labels.
• Dense content pages: compress material to bullets matching the existing slot capacity.
• Decorative or image-heavy pages: avoid forcing long prose into label-sized slots.
• Repeated source pages: every repeated entry must carry a distinct purpose and replacement set; avoid visual repetition unless the repeated layout expresses the same rhetorical pattern.
• Reordered source pages: verify the new sequence reads as a coherent story; template page numbers, decorative section markers, and notes must be updated to match the output order.

Speaker notes (the notes field) — distilled from the ppt-master main pipeline's Logic Construction Phase, scaled to one note per planned slide:

Each notes value is pure spoken narration: write only what a presenter would say aloud, so the same text also works if the deck is later sent through notes_to_audio.py. The note explains and connects; it must not just restate the words already on the slide.

Example notes value for a Chinese content slide:

"notes": "在看清整体市场格局之后，我们把镜头拉近到成都二手房的头部板块。当前挂牌均价同比上涨约百分之十二，但成交周期反而拉长到九十天以上，说明买方观望情绪在加重。这组数据是后面定价策略的基础，请重点留意。"

Step 5: Check Text Capacity

Run the data-based capacity check before applying the plan:

python3 .claude/skills/ppt-master/scripts/template_fill_pptx.py check-plan "<project_dir>/analysis/<stem>.slide_library.json" "<project_dir>/analysis/fill_plan.json" -o "<project_dir>/analysis/check_report.json"

Interpret the report:

check-plan emits stable code fields in its JSON results so warnings can be tracked without parsing message text. Warnings are advisory and do not fail the command; record any intentionally accepted warning in accepted_warnings when it matters for review. Errors are blocking and must be fixed before apply.

Default fitting policy: Check fit against visual capacity, not raw character count. CJK characters, Latin letters, numbers, and punctuation occupy different visual widths; old placeholder text is only a weak signal. Use capacity_visual_width when present, together with slots[].geometry and slots[].text_metrics.font_size_px, to decide whether to rewrite, split, or choose a different source layout. Do not use per-item font shrinking as a default strategy because it breaks template consistency.

Note: check-plan is a pre-apply estimate. The post-apply OfficeCLI gate (Step 7.2) measures the rendered result; treat Step 5 as the cheap first filter, not the final word on fit.

Step 6: Apply the Plan

⛔ BLOCKING GATE: The user has reviewed the planned output order, omitted pages, reused pages, and material-to-layout fit. Set <project_dir>/analysis/fill_plan.json top-level status to "confirmed" only after that review. apply rejects an unconfirmed plan by default; --force exists only for deliberate recovery/debug use.

Run:

python3 .claude/skills/ppt-master/scripts/template_fill_pptx.py apply "<project_dir>/sources/<source.pptx>" "<project_dir>/analysis/fill_plan.json" -o "<project_dir>/exports/<output.pptx>"

By default apply gives every cloned slide a fade transition (0.5s), preserving the v1 route contract. Override it with --transition <effect> (fade / push / wipe / split / strips / cover / random) and --transition-duration <seconds>; pass --transition none for no visual motion, or --transition keep to preserve each source slide's existing transition unchanged. A per-slide transition field overrides the CLI. advance_after keeps click advance enabled and adds timed advance; it also works with none (timing-only transition) and keep (source effect preserved, Choice/Fallback timing updated together).

apply appends a timestamp automatically. For example, -o "<project_dir>/exports/demo.pptx" writes demo_YYYYMMDD_HHMMSS.pptx. If the filename already ends with _YYYYMMDD_HHMMSS, it is left unchanged.

The script:

Animation policy: Template-fill preserves each cloned slide's existing object animation XML (the SVG pipeline's generated object animation defaults are not applied here). Page transitions are the one motion layer this skill writes directly, and apply adds a fade transition by default; change it with apply --transition / a per-slide transition field, or opt out with --transition keep (preserve source) or --transition none. keep preserves direct and mc:AlternateContent transition effects without converting unknown effects to fade; explicit replacement removes the old logical carrier before writing one new carrier. If the user asks to change object-level animation order / timing / effects, treat that as a separate direct-PPTX animation customization task.

Step 7: Validate Output

Three layers, in order: content read-back → OfficeCLI measurement gate → native render pass. The export is not final until all three pass or every remaining finding is explicitly accepted.

7.1 Content read-back

python3 .claude/skills/ppt-master/scripts/template_fill_pptx.py validate "<project_dir>"

The validator finds the latest PPTX in <project_dir>/exports/, runs ppt_to_md.py into <project_dir>/validation/readback.md, and writes <project_dir>/validation/validate_report.json. exports/ must contain only final deliverables.

Verify:

7.2 OfficeCLI measurement gate

🚧 GATE: This scan is required, not optional. check-plan (Step 5) estimates fit; this gate measures the actual rendered frames. Editing stays in fill_plan.json + apply — OfficeCLI only measures and judges.

officecli validate "<project_dir>/exports/<file>.pptx"
officecli view "<project_dir>/exports/<file>.pptx" issues --json

Save the issues --json output to <project_dir>/validation/officecli_issues.json.

Triage validate results (schema errors are triage signals, not automatic failures):

Fix loop for issues findings — repeat until the scan is clean or every remaining finding is recorded in accepted_warnings:

Hard rule: never patch <project_dir>/exports/*.pptx in place. Exports are derived artifacts; every fix goes through fill_plan.json → apply → re-scan.

Loop bound: if the same finding survives 3 fix rounds, stop looping and surface it to the user with the measured numbers and the attempted rewrites — the slot may simply be too small for the required message, which is a page-selection decision (Step 3), not a wording problem.

Missing OfficeCLI → state the install command (npm install -g @officecli/officecli@1.0.135) and record in <project_dir>/validation/ that the gate was skipped. Do not present the export as verified; get the user's explicit acceptance before treating it as final.

7.3 Native render pass

Render every output page and read the images (with PowerPoint installed, default --render auto drives native PowerPoint — ground truth):

officecli view "<project_dir>/exports/<file>.pptx" screenshot --page 1-<N> \
  -o "<project_dir>/validation/pptx_render/deck.png"
# per page: --page <k> -o .../p<k>.png ; whole-deck contact sheet: --grid

On a visual defect, route the fix through the same loop as 7.2: adjust fill_plan.json, re-apply, re-render. Under --render html (no Office installed) apply the known-deviation allowances from verify-pptx-export Step 3 — wrap points ±1 character, chart legend placement, and master date/slide-number placeholders are engine artifacts, not defects.

Note: deeper post-export triage (package part inspection, SVG-route comparison) lives in ppt-master verify-pptx-export; this skill's gate covers the fill-specific failure surface.

## ✅ Template Fill Complete

- [x] Standard PPTX intake extracted from the source deck, including `<stem>.slide_library.json`
- [x] `fill_plan.json` selects only pages that fit the target story
- [x] User reviewed the story structure and `fill_plan.json` has `status: "confirmed"`
- [x] `check-plan` run; errors fixed; warnings reviewed / optionally recorded in `accepted_warnings`
- [x] Output PPTX generated through direct OOXML text replacement
- [x] Speaker notes embedded when `notes` fields are present
- [x] `template_fill_pptx.py validate` read-back check passed
- [x] OfficeCLI `validate` triaged and `issues --json` clean (or every remaining finding recorded in `accepted_warnings`)
- [x] All pages rendered to `validation/pptx_render/` and visually checked; fixes routed through `fill_plan.json` → `apply`

Current Boundary