theme-template-ppt

name

theme-template-ppt

description

Create PowerPoint decks from assets/template.pptx by first structuring each slide's core claim, then inspecting/ranking template slide-master layouts, deciding and locking the assigned layout (`layout_name` or `layout`) when needed, and finally writing content to fit selected placeholders. Use when asked to research a topic, draft slide headers, expand headers into slide-ready content, generate chart/table visuals, run build/lint scripts, and return final .pptx outputs. Do not use for Python environment provisioning (use python-venv).

Theme Template PPT

Create a PowerPoint deck from a theme and an assets template while keeping each slide visually clear and non-busy.

Skill Boundary

• This skill handles:
  • research and draft slide content,
  • create deck/chart JSON inputs,
  • inspect template master layouts,
  • run make_chart.py, build_pptx.py, and lint_pptx.py,
  • return output paths and source list.
• This skill does not provision Python environments.
• Run this workflow only after the environment is prepared (for example by python-venv).

Hard Rules

• Keep responsibility separation:
  • python-venv: environment creation/switch/dependency install only.
  • theme-template-ppt: research/planning/build/lint/output only.
• Do not call python-venv scripts from this skill.
• In LocalPlayground skill_run_script, set path to files under this skill's scripts/ only.
• Never pass executables like python3, bash, or uv as skill_run_script.path.
• Do not use skill_read_asset for files under scripts/ or references/.
• Do not read assets/template.pptx as base64 or plain text.
• Do not run skill_list_resources just to inspect template internals.
• Use only layouts that already exist in template slide masters.
• Determine layout first from page intent + master-placeholder composition.
• Before writing detailed page copy, verbalize each page intent first (for example: title_cover, text_dense, text_brief, visual_split, visual_focus, table_comparison, table_focus, hybrid_data).
• Match layout by both title semantics and composition features (placeholder counts, column split, title position, visual/table slots), not by a single keyword.
• Reduce usage bias by preferring less-used layouts when multiple candidates are similarly suitable.
• Fill selected layout placeholders after layout selection (title/subtitle/body/visual/table) and avoid absolute-position overrides unless explicitly required.
• When a layout has multiple body placeholders, distribute bullets across suitable body placeholders (prefer larger text slots first) instead of forcing all bullets into one box.
• Use scripts only for deterministic steps (layout inspection/ranking, build/lint, placeholder insertion).
• Let LLM handle semantic work (per-slide claim structuring, candidate comparison reasoning, and rewriting content to fit selected placeholder slots).
• After deciding layout, lock it in plan using layout_name (preferred) or layout (catalog index). If omitted, renderer auto-selects.
• Always include agenda and summary slides.
• Control section order via plan.auto_slide_order (agenda,title,content,summary by default).
• The runtime template can be replaced for each use; always inspect and validate masters every run.
• If required layout profiles are missing, create and add them to the slide master before appending slides.
• If MCP server mcp-mermaid is connected, proactively generate architecture/process diagrams through it and prefer those visuals over text-only explanations.
• Save Mermaid-rendered diagram files only under the same active work directory, using "$WORK_DIR/assets/generated/mermaid/".
• Do not write Mermaid output files outside the active work directory.
• Reference Mermaid files from slide visual.path using paths resolved from "$WORK_DIR/deck_plan.json".
• Never pass non-JSON files to:
  • scripts/make_chart.py --spec
  • scripts/build_pptx.py --plan
• Keep output language aligned with user prompt language across:
  • slide titles/body text,
  • chart titles/labels/legends,
  • table headers/cells and captions.
• Set plan.language (ja or en) and pass matching language in chart specs.
• Always run scripts/ensure_workdir_key.bash once before build/lint/chart steps.
• If required runtime dependencies are missing, stop and ask for environment provisioning handoff.

Input Contract

• Collect: theme, target audience, objective, required decision/action, preferred slide count, and deadline.
• Collect: optional slide_title for output filename.
• Use assets/template.pptx as the canonical template.
• Place reusable visuals (logo/icons/brand images) in assets/.
• Ask focused follow-up questions only when required inputs are missing.

Work Directory and Output Policy

• Use this fixed root: ~/.foundry_local_playground/outputs/pptx/.
• Use this fixed working/output directory pattern: ~/.foundry_local_playground/outputs/pptx/<work_key>/.
• Work key priority:
  • --thread-key
  • THEME_TEMPLATE_PPT_WORK_KEY
  • fallback envs (PPTX_WORKDIR_KEY, CODEX_THREAD_ID)
  • auto-generated unique key
• In LocalPlayground, persist THEME_TEMPLATE_PPT_WORK_KEY across turns via scripts/ensure_workdir_key.bash.
• Stage template in that directory before building slides.
• Insert slides in order into the staged template.
• Save final .pptx in the same directory.

Python Dependencies

• Do not install dependencies in this skill.
• Hand off dependency setup to python-venv skill before running this skill.
• Packages:
  • python-pptx
  • Pillow
  • matplotlib
  • japanize-matplotlib

Font Policy (Matplotlib Japanese Safety)

• For Japanese charts, ensure one of the following exists:
  • japanize-matplotlib is installed,
  • font_path is specified in chart spec,
  • Japanese font files are available under assets/fonts/.
• Prefer explicit font_path for deterministic rendering in CI/runtime.
• Keep chart font family consistent with template tone (for example Noto Sans JP).

Script Input Contract (Critical)

• scripts/make_chart.py --spec accepts:
  • JSON file path only.
• scripts/make_chart.py also supports inline quick args when --spec is omitted:
  • --type, --labels, --values, optional --title.
• scripts/build_pptx.py --plan accepts:
  • JSON file path only.
• scripts/build_pptx.py --suggest-layouts --plan accepts:
  • JSON file path only, and prints ranked layout candidates per slide.
• scripts/add_slide.py --spec accepts:
  • JSON file path only.
• Never pass Markdown, text requirements, or PPT/PPTX files as --spec or --plan.
• Always write machine-readable JSON to files before running build/lint steps.
• Always pass absolute JSON file paths to scripts.
• Required before build:
  • <work_dir>/deck_plan.json (required)
• Optional JSON files:
  • <work_dir>/chart_spec_*.json (when generating charts)
  • <work_dir>/slide_spec_*.json (when appending slides manually)
• Run JSON preflight before script execution:
  • scripts/validate_json.py <chart_spec.json>
  • scripts/validate_json.py <deck_plan.json>

Workflow

1. Ensure Workdir Key and Reuse It

• Before planning content, fix work key in thread environment:

scripts/ensure_workdir_key.bash

• Use the same THEME_TEMPLATE_PPT_WORK_KEY on later turns in the same thread.

2. Define Brief and Design System First

• Fix communication brief in plain language before drafting slides:
  • audience,
  • objective,
  • required decision/action.
• Define design system tokens before writing page copy:
  • heading hierarchy (title > subtitle > body > caption),
  • allowed font families and size scale,
  • base/accent/warning color roles,
  • target margins and guide alignment rules.
• Keep one slide = one message.
• Keep narrative order explicit (agenda -> context -> analysis -> recommendation -> summary).

3. Research Theme on the Web

• Search the web based on the theme.
• Prefer primary or official sources.
• Cross-check key claims with at least two sources.
• Record source URLs and retrieval dates.

4. Inspect Template Slide Masters First

• Before planning content, inspect layout catalog from template:

scripts/build_pptx.py --list-layouts

• Optional: save catalog JSON for plan authoring:

scripts/build_pptx.py --list-layouts --layout-report ./layout-catalog.json

• Use this catalog to understand which layout patterns exist in the template.
• The script auto-selects one of these existing master layouts for each slide.
• If required profiles are missing (title/content/visual/table), the script clones and adds missing layouts.

5. Draft Story Headers and Per-Slide Claim

• Produce a bullet list of slide headers before writing slide bodies.
• Keep at least five headers unless the user specifies a different count.
• For each header, attach:
  • one-line claim/message,
  • one layout intent label (title_cover, text_dense, text_brief, visual_split, visual_focus, table_comparison, table_focus, hybrid_data).

6. Build Message-First Skeleton (No Final Copy Yet)

• Expand each header into one slide object with message and intent first.
• Decide required placeholder types first (body-only / visual+body / table+body / hybrid).
• Do not finalize detailed bullet wording before layout decision.
• Attach source links to factual claims.
• Keep terminology, units, dates, and language consistent across all slides.
• Build an intent-first plan skeleton using references/deck-plan-schema.md.

7. Emit Skeleton JSON and Validate

• Resolve the working directory once and keep it in this thread:

WORK_DIR="$HOME/.foundry_local_playground/outputs/pptx/$THEME_TEMPLATE_PPT_WORK_KEY"
mkdir -p "$WORK_DIR"

• Write deck plan JSON to the required file path:

cat > "$WORK_DIR/deck_plan.json" <<'JSON'
{
  "language": "ja",
  "slides": [
    {
      "title": "イントロダクション",
      "intent": "text_brief",
      "bullets": [
        "要点1",
        "要点2"
      ]
    }
  ]
}
JSON

• Validate JSON before build:

scripts/validate_json.py "$WORK_DIR/deck_plan.json"

• If charts are needed, write chart spec JSON under the same work directory (for example "$WORK_DIR/chart_spec_001.json"), then validate it with scripts/validate_json.py.
• Do not call build_pptx.py until "$WORK_DIR/deck_plan.json" exists and passes validation.

8. Review Layout Candidates and Decide Assigned Layout

• Run per-slide candidate ranking from skeleton JSON:

WORK_DIR="$HOME/.foundry_local_playground/outputs/pptx/$THEME_TEMPLATE_PPT_WORK_KEY"
scripts/build_pptx.py \
  --plan "$WORK_DIR/deck_plan.json" \
  --suggest-layouts \
  --candidate-limit 3 \
  --suggestions-report "$WORK_DIR/layout-suggestions.json"

• For each slide, compare candidates using:
  • claim/message fit,
  • placeholder profile (body/visual/table slots),
  • column split and title position.
• Decide assigned layout per slide and lock it in plan:
  • prefer layout_name,
  • optionally use layout (catalog index from layout-catalog.json / suggestions output).

9. Rewrite Content to Fit Selected Layout Placeholders

• Let LLM rewrite bullets/captions after layout lock so content matches selected blank structure.
• Fill placeholders in this order:
  • title/subtitle placeholder,
  • visual/table placeholder,
  • body placeholders (distribute bullets across suitable slots; prioritize larger text areas).
• Avoid manual absolute coordinates unless layout placeholders are unavailable.
• Keep this order strict: claim -> candidate review -> layout decision -> content rewrite -> fill placeholders.

10. Fix Output Language from Prompt

• Detect user prompt language first (ja or en).
• Set plan.language to that value.
• Keep all slide/chart/table text in that language unless user explicitly asks bilingual output.
• Add language to every chart spec and keep it aligned with plan.language.

11. Plan Visuals Early and Aggressively

• Convert dense text into visuals whenever possible.
• Target at least one visual slide in every two slides.
• Use tables for comparisons, KPI snapshots, and option matrices.
• If mcp-mermaid is connected, create architecture/system-flow diagrams with it first for topology, component interaction, and sequence-style content.
• Prefer Mermaid-generated diagrams over ad-hoc text blocks when both can explain the same content.
• Export Mermaid outputs to "$WORK_DIR/assets/generated/mermaid/" and attach them via each slide's visual.path.
• Generate charts/figures with scripts/make_chart.py when needed.
• Build chart JSON from references/chart-spec-schema.md.
• Save generated images to a predictable folder (for example assets/generated/).
• Ensure chart input passed to make_chart.py is a valid JSON file path (or use inline quick args without JSON).

12. Build Deck from Template

• Use scripts/build_pptx.py to stage template and initialize output .pptx.
• Use scripts/add_slide.py to append one slide at a time from slide JSON specs.
• Keep --template omitted by default so the script uses assets/template.pptx.
• Keep master-layout auto detection enabled.
• The build flow always inserts agenda (目次/Agenda) and summary (まとめ/Summary) sections.
• Section order is configurable with plan.auto_slide_order.
• The build flow creates one output .pptx first, then appends slides sequentially.
• If generation fails mid-run, keep the partial .pptx and resume from the current plan state.
• Example:

WORK_DIR="$HOME/.foundry_local_playground/outputs/pptx/$THEME_TEMPLATE_PPT_WORK_KEY"
scripts/build_pptx.py \
  --slide-title "market-outlook-2026" \
  --plan "$WORK_DIR/deck_plan.json" \
  --output final-deck.pptx

• Optional direct append example:

WORK_DIR="$HOME/.foundry_local_playground/outputs/pptx/$THEME_TEMPLATE_PPT_WORK_KEY"
scripts/add_slide.py \
  --deck "$WORK_DIR/final-deck.pptx" \
  --kind content \
  --spec "$WORK_DIR/slide_spec_001.json" \
  --language ja

13. Validate Quality Gates Automatically

• Run scripts/lint_pptx.py after generation with language and style checks.
• Example:

WORK_DIR="$HOME/.foundry_local_playground/outputs/pptx/$THEME_TEMPLATE_PPT_WORK_KEY"
scripts/lint_pptx.py \
  --input "$WORK_DIR/final-deck.pptx" \
  --language ja \
  --require-sources-notes \
  --fail-on-warning

• If warnings exist, fix by:
  • splitting crowded slides,
  • reducing bullet count,
  • replacing text blocks with charts/diagrams/tables,
  • reducing font/style variation,
  • improving margins/alignment/layout balance.
• Re-run lint until the deck passes quality gates from references/quality-gates.md.

14. Perform Manual Visual Polish Pass

• Check spacing and alignment against template guides.
• Check image quality and crop consistency.
• Check chart simplification (remove unnecessary decoration).
• Check icon/line/shadow style consistency.

15. Enforce Language and Source Consistency

• Confirm plan.language matches prompt language.
• Confirm all slide text and chart labels match plan.language.
• For Japanese charts, confirm selected font can render all labels (no tofu boxes).
• Keep source sections in speaker notes with the same Sources: style.

16. Perform Final Consistency Pass

• Check logical consistency across all slides.
• Check terminology, unit, and timeline consistency.
• Check that visual usage is sufficient and text density is controlled.
• Check that every slide message supports the final decision/action.

17. Save and Report

• Save final deck and return absolute path.
• Return:
  • work directory absolute path,
  • output .pptx absolute path,
  • staged template absolute path,
  • source URL list,
  • summary of major revisions made in quality pass,
  • layout-intent summary from build logs.

Script Quick Reference

• scripts/build_pptx.py: Inspect layouts, rank per-slide layout candidates (--suggest-layouts), initialize output .pptx, and orchestrate sequential append.
• scripts/add_slide.py: Append one title/content slide to an existing .pptx.
• scripts/lint_pptx.py: Detect density, layout bias, typography inconsistency, margin/guide issues, and source/language format drift.
• scripts/make_chart.py: Generate chart PNG files from simple JSON specs.
• scripts/ensure_workdir_key.bash: Create/reuse THEME_TEMPLATE_PPT_WORK_KEY in environment.
• scripts/validate_json.py: Validate JSON input files before build/chart runs.

References

• references/deck-plan-schema.md: Plan schema for build_pptx.py.
• references/chart-spec-schema.md: Chart schema for make_chart.py.
• references/quality-gates.md: Slide density and visual-usage thresholds.