Branded Pptx Generator

Branded PPTX Generation

Purpose

Turn (template + content brief) into a finished, brand-compliant .pptx.

Architecture

Guiding Posture (summary)

The template is the law. Claude is the steward, not the author. The three modes (strict / balanced / creative) are three distinct working postures that govern how much design authority Claude exercises over the template's three pillars (brand identity, design system, demonstration).

For the full posture, the three personas, the mode manifesto, and how to handle mode conflicts, see [references/mode-philosophy.md](references/mode-philosophy.md). Read it at the start of every session.

Dependency: pptx-profiler skill (template analysis)

Located at $PROFILER_SKILL = $SKILLS_ROOT/pptx-profiler. Produces $PROFILE ({Brand}.profile/template-profile.json) and composer-digest.json.

Tools from the pptx skill (deterministic PPTX operations)

Located at $PPTX_SKILL/scripts/ where $PPTX_SKILL = $SKILLS_ROOT/pptx.

| Tool | Purpose | |------|---------| | office/unpack.py | Unpack .pptx → XML directory | | office/pack.py | Pack XML directory → .pptx (with validation) | | add_slide.py | Clone an existing slide or create one from a layout | | clean.py | Remove orphaned slides and resources | | office/soffice.py | Render .pptx → PDF via LibreOffice | | office/validate.py | OOXML schema validation + auto-repair | | office/potx2pptx.py | Convert .potx → .pptx (patch ContentType) | | markitdown | Quick text extraction (python -m markitdown) |

This skill's tools (final compliance check)

Located at $SKILL/scripts/ where $SKILL = $SKILLS_ROOT/branded-pptx-generator.

| Tool | Purpose | Status | |------|---------|--------| | validate_plan.py | Step 5 checkpoint — JSON Schema + business rules (taskId uniqueness, bookends, divider consistency, mode×strategy, layoutRef existence, theme-slot palette, plan/policy mode alignment) | ✅ Available | | compliance_checker.py | Locked-tier compliance check on final .pptx | ✅ Available | | extract_slide_elements.py | Raw structural extraction of a sample slide for on-demand design analysis | ✅ Available |

This skill's reference artifacts (schemas and prompts)

| Artifact | Purpose | |----------|---------| | schemas/content_outline_schema.json | JSON Schema for content-outline.json (Step 4) | | schemas/slide_plan_schema.json | JSON Schema for slide-plan.json (Step 5a) | | schemas/style_policy_schema.json | JSON Schema for style-policy.json (Step 5b, incl. aestheticGuidance) | | schemas/slide_design_schema.json | Output schema for slide visual design analysis (Phase 1+2) | | schemas/*.example.json | Filled-in examples: contentoutline, slideplan, stylepolicy, slidecontent, generation_report | | prompts/annotate-slide-design.md | VLM subagent prompt for Phase 2 semantic annotation |

Claude's own capabilities (judgment and generation)

• Mode inference from the user's request
• Outline + slide plan + shared style policy authoring
• Per-slide content fitting, placeholder filling, XML edits
• python-pptx code generation for complex visuals
• Visual QA via subagents and fix-and-verify reasoning

---

Workflow

Skill path variables (initialization before any other command):

export SKILLS_ROOT=".claude/skills"
export SKILL="$SKILLS_ROOT/branded-pptx-generator"
export PROFILER_SKILL="$SKILLS_ROOT/pptx-profiler"
export PPTX_SKILL="$SKILLS_ROOT/pptx"

Eleven core steps. Execute in order. Each step ends with a checkpoint. Each step below lists the critical rules inline; for full procedural detail, JSON examples, and edge cases, read the linked per-step reference before executing that step.

Step 1 — Obtain Template Profile

TEMPLATE="templates/.potx"                       # user-provided
TEMPLATE_FOLDER=$(dirname "$TEMPLATE")
TEMPLATE_FILE=$(basename "$TEMPLATE")
BRAND=$(basename "$TEMPLATE" | sed 's/\.\(potx\|pptx\)$//')

PROFILE_DIR="$(pwd)/${TEMPLATE_FOLDER}/${BRAND}.profile"
PROFILE="${PROFILE_DIR}/template-profile.json"
DIGEST="${PROFILE_DIR}/composer-digest.json"

• If both files already exist and the template hasn't changed,

reuse them.

• Otherwise, run the pptx-profiler skill end-to-end:

`` Read $SKILLS_ROOT/pptx-profiler/SKILL.md and execute its workflow on $TEMPLATE. Produce $PROFILE and $DIGEST (preview renders are cached in $PROFILE_DIR). ``

composer-digest.json is the smaller, decision-ready summary — prefer reading it during planning. Its structure is defined by $SKILLS_ROOT/pptx-profiler/schemas/composer_digest_schema.json. Fall back to the full $PROFILE only when you need raw structural details (placeholder idx, exact positions, etc.).

Checkpoint: $PROFILE and $DIGEST exist. Layouts have inferred_type, content_capacity; design_language is populated; sample slides (if any) have role and clone-suitability fields (cloneCandidate, layoutRelationship, styleSourceType, styleRefSuitability, layoutMismatchSummary).

Step 2 — Determine Mode

Three modes governing design authority over template layers. Each mode is a distinct working persona — see [references/mode-philosophy.md](references/mode-philosophy.md) for the full persona descriptions, when each fits, and the mode manifesto.

| Mode | Brand Identity | Design System | Demonstration | |---|---|---|---| | strict | Rule | Rule | Rule | | balanced | Rule | Rule | Reference | | creative | Rule | Reference | Reference |

• Strict — Content-filling machine. No design decisions.
• Balanced — Follows the style guide, interprets examples.
• Creative — Creates within the brand; template is inspiration.

Read the user's request and $DIGEST. Two signal sources:

1. Content purpose (from the user's request) — the primary signal.

Formal/regulated → strict. Standard business → balanced. Expressive/audience-facing → creative.

1. Template richness (from $DIGEST → template) — a secondary nudge.

Layout-rich templates (>10 layouts + multiple samples) lean strict; minimal templates (3–5 layouts, few/no samples) lean creative.

When the two signals conflict, content purpose wins. Default to balanced when unclear.

Checkpoint: A single mode chosen. If the request was ambiguous, note your reasoning (including template richness factor) briefly to the user.

Step 3 — Set Up Session Directory

MODE=""                                           # from Step 2
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
SESSION="sessions/${TIMESTAMP}_${BRAND}_${MODE}"

mkdir -p "$SESSION"
cp "$TEMPLATE" "$SESSION/"
cd "$SESSION"

All subsequent commands run from $SESSION.

Checkpoint: $SESSION/.potx (or .pptx) exists.

Step 4 — Create Content Outline

Analyze the user's request → content-outline.json with intent, narrative arc, and per-slide semantic role allocation. Pure LLM reasoning.

• Outputs: content-outline.json (schema:

[schemas/contentoutlineschema.json](schemas/contentoutlineschema.json)).

• Key rules: One cover + one closing; sections with ≥ 2 body slides

get a divider; respect user's slide count or default 8–12.

• Checkpoint: Slide counts sum to total; every slot has a semanticRole.

> Full procedure: [references/step4-content-outline.md](references/step4-content-outline.md)

Step 5 — Plan the Deck

Two artifacts in one pass: slide-plan.json (layout mapping) + style-policy.json (shared style), plus slide-content.json (full text).

5a — Build the slide plan

Map each slide slot to a template layout using $DIGEST. Select strategy per slide: clone-sample > clone-layout > augmented-clone > spec-composed (lightest that works). See [references/generation-modes.md](references/generation-modes.md) for mode-dependent strategy availability.

5b — Freeze the shared style policy

One style-policy.json for the whole deck. Pull values from $DIGEST → designDirectives. Populate aestheticGuidance from $DIGEST → aestheticPrinciples when available.

5c — Generate slide content

Produce slide-content.json with capacity-aware text sizing per layout placeholder. All content authored in a single pass for cross-slide consistency. Agenda page numbers deferred as "TBD".

• Checkpoint: slide-plan.json, style-policy.json, and

slide-content.json exist; plan respects consistency rules. Schemas: [slideplanschema.json](schemas/slideplanschema.json), [stylepolicyschema.json](schemas/stylepolicyschema.json).

python $SKILL/scripts/validate_plan.py "$SESSION" --profile $PROFILE

> Full procedure (5a–5c, including aestheticGuidance enrichment and > capacity-aware sizing): [references/step5-deck-plan.md](references/step5-deck-plan.md)

Step 6 — Initialize the Working PPTX

Convert .potx → .pptx if needed, then unpack for XML editing.

python $PPTX_SKILL/scripts/office/potx2pptx.py "$TEMPLATE_FILE" -o "$PPTX_FILE"  # if .potx
python $PPTX_SKILL/scripts/office/unpack.py "$PPTX_FILE" unpacked/

• Checkpoint: unpacked/ppt/presentation.xml exists.

> Full procedure: [references/step6-init-pptx.md](references/step6-init-pptx.md)

Step 7 — Generate Slides

Process slides grouped by strategy. Delegate per-slide XML editing to subagents. All XML edits follow the [XML Editing Rules](references/xml-editing-rules.md).

Critical rules:

• Always delegate per-slide editing to subagents — keeps the main

context clean. Run add_slide.py for all slides first, update `` in one pass, then dispatch one subagent per slide.

• Use exact text from slide-content.json — subagents must not

invent or modify content.

• Theme references over hex for any added/modified elements.
• Mode boundaries hold: augmented-clone is forbidden in strict;

spec-composed is forbidden in strict unless no layout fits at all.

| Strategy | Approach | |---|---| | clone-sample / clone-layout | add_slide.py then edit XML | | augmented-clone | Clone + structural modifications | | spec-composed | See [references/spec-composed-strategy.md](references/spec-composed-strategy.md) |

• Checkpoint: Every task in slide-plan.json has a `` entry.

> Full procedure (subagent prompt template, per-strategy details): > [references/step7-generate-slides.md](references/step7-generate-slides.md)

Step 8 — Assemble & Pack

Drop template sample slides, reorder to match plan, rebuild sections, clean orphans, patch agenda page numbers, detach stale chart data, verify chart cache integrity, reject `` connectors, then pack.

Critical rules (each is a confirmed PowerPoint repair trigger if skipped):

• Rebuild `` — template's section list still

references old sample slide IDs; replace entirely with new sections from content-outline.json.

• Clean [Content_Types].xml — clean.py does NOT remove ``

entries for deleted files; orphans cause repair prompts.

• Detach stale chart `` — any edited chart's

embedded .xlsx is stale; remove the ref + delete the xlsx.

• Verify chart ` matches ` count — subagents

often change data points without updating the count.

• Reject `` connectors before packing — they pass all

automated checks but cause PowerPoint COM to refuse the file.

python $PPTX_SKILL/scripts/clean.py unpacked/
python $PPTX_SKILL/scripts/office/pack.py unpacked/ output.pptx --original $TEMPLATE_FILE

• Checkpoint: output.pptx is valid OOXML; no `` elements;

no orphaned [Content_Types].xml entries.

> Full procedure (10 sub-steps with snippets): > [references/step8-assemble-pack.md](references/step8-assemble-pack.md)

Step 9 — Check Compliance

python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|click to|insert"
python $SKILL/scripts/compliance_checker.py output.pptx --profile $PROFILE --output compliance-report.json

• Checkpoint: No leftover placeholders; zero locked violations.

> Full procedure: [references/step9-compliance.md](references/step9-compliance.md)

Step 10 — Inspect Visuals

Run schema validation, render slide previews, and launch a visual QA subagent. See [references/brand-compliance.md](references/brand-compliance.md) for what to check.

Critical rules:

• Validate before rendering. Run `validate.py --original $TEMPLATE_FILE

--auto-repair` first; do not spend tokens on visual QA if the file is structurally invalid.

• Always use a subagent for visual inspection — never self-inspect,

even for 2–3 slides. The #1 thing to flag is style drift across recurring elements (dividers, covers).

• Render at --width 1920 so the subagent can read fine details.
• Locked elements are visual-only: logo positions, footer structure,

disclaimer/copyright are not covered by compliance_checker.py — the subagent must verify them.

python $PPTX_SKILL/scripts/office/validate.py output.pptx --original $TEMPLATE_FILE --auto-repair
python $PROFILER_SKILL/scripts/render_samples.py output.pptx -o slide-previews/ --width 1920

• Checkpoint: Issue list collected from validator + subagent.

> Full procedure (full subagent prompt template): > [references/step10-inspect-visuals.md](references/step10-inspect-visuals.md)

Step 11 — Fix, Verify & Deliver

Fix issues at source → re-pack → re-render → re-inspect. Maximum 1 fix-and-verify cycle.

Critical rules:

• Fix at source, not in the packed .pptx. Edit unpacked/ then

re-pack.

• Recompute agenda page numbers if fixes added/removed slides

(same procedure as Step 8 sub-step 6).

• Maximum 1 cycle. If issues persist after one fix pass, deliver

with a written summary of remaining issues — don't loop.

• Write generation-report.json capturing mode, slide count,

layouts used, strategy mix, compliance result, unresolved issues.

cp output.pptx "outputs/${BRAND}_${MODE}_${TIMESTAMP}_${TOPIC_SLUG}.pptx"

• Outputs: generation-report.json, final .pptx in outputs/.

> Full procedure (report schema, naming convention): > [references/step11-fix-deliver.md](references/step11-fix-deliver.md)

---

Output Artifacts

$TEMPLATE_FOLDER/
└── {Brand}.profile/                  # produced by pptx-profiler, reused here
    ├── template-profile.json
    ├── composer-digest.json
    ├── slide-elements-slide{N}.json  # Phase 1 extraction cache (on demand)
    └── slide-design-slide{N}.json    # Phase 1+2 full analysis cache (on demand)

$SESSION/
├── {Brand}.potx                      # copy of source template
├── content-outline.json              # Step 4
├── slide-plan.json                   # Step 5a
├── style-policy.json                 # Step 5b
├── slide-content.json                # Step 5c
├── unpacked/                         # editable XML (Step 6–8)
├── output.pptx                       # final deck (Step 8, working name)
├── compliance-report.json            # compliance checker output (Step 9)
├── generation-report.json            # final summary report (Step 11)
├── slide-previews/                   # rendered previews (Step 10)
│   └── slide{N}.jpg
└── generate_{taskId}.py              # only for spec-composed / augmented-clone slides

outputs/
└── {Brand}_{mode}_{timestamp}_{topic_slug}.pptx   # delivered deck (Step 11)

---

XML Editing Rules

See [references/xml-editing-rules.md](references/xml-editing-rules.md) for the full list. Key rules: use lxml.etree (never stdlib ET), never use `` connectors, reference theme color slots over hex.

---

Style Consistency Principles

These are the failure modes that distinguish a "branded" deck from a generic one. Internalize them:

1. One source per recurring slide kind. Every section divider

clones the same source slide. Cover and closing come from the same family. Decided once in style-policy.json, not per slide.

1. **Theme

…

Source & license

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

• Author: sanpingli
• Source: sanpingli/skills
• License: MIT

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