Presentation Skill

Presentation Deck Skill

Generate professional, visually rich native PowerPoint (.pptx) presentations. See references/decision-tree.md for workflow routing.

Quick Reference

Phase 0 — Detect Mode

Determine the correct mode before proceeding:

Mode A: From Scratch No template file provided. Claude generates a fully styled deck using the outline + design system.

Mode B: Template-Based User provides an existing .pptx file to use as the visual template. Read references/template-mode.md.

Mode C: Image-Rich Deck User has shared one or more images (photos, diagrams, screenshots, brand assets) to embed in specific slides. Read references/image-handling.md. This mode can be combined with A or B.

Mode D: Edit Existing Deck User provides a finished .pptx and wants changes (fix text, swap images, add/remove/reorder slides, or split/merge decks via edit_deck.py extract/append). Do NOT rebuild — edit surgically. Read references/editing.md. Skip Phases 1–3 and go straight to the editing workflow + Phase 4 QA. Exception: when the user wants the whole deck restyled/normalized ("make it match our brand", "clean this up"), use the restyle path — deck_to_outline.py extracts the content into an outline (with a fidelity report), then Phases 2–4 run as normal on that outline.

Mode E: Revise a Deck This Toolchain Built The deck came back with reviewer comments, emailed feedback, or fresh data, and its outline still exists. Do NOT rebuild the whole deck (that clobbers hand edits) and do NOT hand-edit the .pptx (the outline stops being the source of truth). Fix the outline, then patch only the affected slides — edit_deck.py comments plan|apply for comments, refresh_deck.py for new data, outline_ops.py for structure, patch_deck.py for the swap. Read references/editing.md § "Revision loop (decks this toolchain built)", then run Phase 4 QA.

Phase 1 — Content & Style Discovery

Ask ONE clarifying message covering all of the below before starting. Combine into a single natural prompt, not a numbered list.

1. Topic / title — What is the presentation about? Who is the audience?
2. Length — Approximately how many slides? (Short 5–10 / Medium 10–20 / Long 20+)
3. Purpose — Pitch deck / Internal strategy / Client presentation / Conference talk / Tutorial
4. Tone — Bold & dark / Clean & corporate / Warm & editorial / Technical & minimal
5. User images — Has the user shared any images? If yes, ask which slides to place them on (see references/image-handling.md).
6. Template — Has the user provided a .pptx template file? If yes, switch to Mode B.
7. Source documents — Users may supply PDF/docx/xlsx/CSV source documents to draft the outline from; CSV/xlsx files can also feed charts directly via - Data-File: path.csv (provenance is stamped into speaker notes). For decks where numbers must be defensible (board/consulting), offer an evidence ledger (**Evidence-File:** + - Evidence: refs — references/generation-guide.md).
8. Recurring client / engagement — if this deck is for a client the skill has built for before, check <assets>/profiles/ for a matching profile. When one exists, build with **Profile:** <name> (or --profile <name>) and read <assets>/profiles/<name>.lessons.md before writing the outline — it lists the QA findings that recurred on past decks for this client, so you can avoid them this time instead of rediscovering them in Phase 4. See references/generation-guide.md.

After gathering answers, research the topic if needed using available tools.

Phase 2 — Outline (User Approval Gate)

0. Strategy/consulting decks first draft the storyline (references/storyline.md): SCQA the executive summary, dot-dash the body, then run the titles test (build_deck.py outline.md --titles). Action titles only — full-sentence takeaways, never topic labels.
1. Write the slide outline in markdown (one ## Slide N: section per slide) using the exact syntax in references/generation-guide.md. Follow its Design Rules: vary layouts, use icons (icon:name) on bullet slides, write - Notes: speaker notes for every slide, and - Source: on every exhibit.
2. Validate it: python3 scripts/build_deck.py outline.md --check — fix errors; address warnings (missing notes, house-style findings such as marketing adjectives, hedges, passive or duplicate titles, etc.).
3. Show the outline to the user and ask for approval or edits before building. The outline is the reviewable artifact; changing a slide here is cheap, regenerating a deck is not. Skip this gate only if the user explicitly asked for a one-shot build.

Phase 3 — Generation

1. If user images are involved, normalize first: python3 scripts/prep_images.py assets/user-images/
2. Run python3 scripts/build_deck.py outline.md --output deck.pptx [--palette X] [--template T.pptx] [--assets-dir DIR] [--density compact|comfortable] [--variant a|b|c] [--ghost] [--profile NAME] [--verbatim]
   • --ghost builds a skeleton deck (real action titles, grey labeled exhibit placeholders) for storyline sign-off before investing in content.
   • --profile NAME applies a saved engagement profile (palette, footer, stamp, banned phrases, mandatory slides); --verbatim locks the copy so outline text lands byte-identical.
   • Custom brand palettes: drop <name>.json into <assets>/palettes/ and use --palette <name> (schema: references/generation-guide.md).
   • Brand-match decks: python3 scripts/brand_kit.py <domain> --name <n> generates a custom palette (+ logo) from a company's web presence, then build with --palette <n>.
3. The build fails fast on validation errors. If any slide fails during build, no .pptx is written.

Optional: python3 scripts/gen_appendix.py outline.md for pitch/strategy appendix skeleton; python3 scripts/gen_handout.py outline.md for a pre-read markdown handout.

Phase 4 — QA (Required)

Never skip QA. Seven complementary checks (see references/qa-guide.md):

1. Programmatic: python3 scripts/qa_check.py deck.pptx — bounds, tiny text, contrast, font-true overflow, and editability warnings (text parked on a shape, free connectors, tiny fonts + dead space). --accessibility for WCAG AA strict mode; --integrity for Keynote/macOS package hygiene (always runs) plus optional OOXML schema validation
2. Deck lint: python3 scripts/pptx_lint.py deck.pptx --palette <palette> — cross-slide consistency in fix order (page sequence, jiggle, axis honesty, chart honesty, numeric consistency, off-palette colors, off-brand fonts/type scale, AI tells, layout monotony, density rhythm)
3. Content diff: python3 scripts/diff_deck.py outline.md deck.pptx — dropped outline content is an error, untraceable "added" deck text a warning (--strict to escalate)
4. Geometry (pre-render): python3 scripts/geometry_report.py deck.pptx — deterministic overlap/spacing/whitespace/balance metrics; fix findings before spending a render
5. Visual: python3 scripts/render_slides.py deck.pptx --grid --out assets/qa-thumbs/ + fresh-eyes subagent answering the binary checklist from python3 scripts/qa_checklist.py outline.md (see references/qa-guide.md; grid cells are numbered)
6. Consistency (LLM): python3 scripts/qa_check.py deck.pptx --numbers + titles test — cross-check totals, repeated KPIs, title claims (see references/qa-guide.md)
7. Fix loop: edit outline → rebuild → re-run all checks until clean; on revision cycles, diff against the last delivered render with python3 scripts/visual_regress.py assets/qa-baseline/ assets/qa-current/

Before a deck leaves the building: python3 scripts/pptx_lint.py deck.pptx --client-safe [--denylist terms.txt] — comments, hidden slides and denylisted client/internal terms are errors; clean them with edit_deck.py clean --client-safe (references/editing.md).

Final gate: python3 scripts/qa_summary.py deck.pptx --outline outline.md --palette <p> --output qa-summary.json unifies checks 1-4 into one machine-readable record (exit 1 on any error) — its stats plus the deck's editability level (L0–L5) double as the delivery note. Add --comments reviewed.pptx to get a copy of the deck with every finding pinned to its slide as a PowerPoint comment. On a profiled deck add --profile <name> so findings that recur across runs are appended to <assets>/profiles/<name>.lessons.md — the file Phase 1 tells you to read next time.

Deliver the .pptx and the thumbnail grid together.

Dependencies

pip install -r requirements.txt
pip install pillow-heif   # only needed for HEIC (iPhone) image inputs
pip install cairosvg      # optional: Lucide SVG icon fallback (Tabler PNG needs nothing)
# Optional: rendered diagrams (references/diagrams.md)
# brew install graphviz            # .dot/.gv support
# npm i -g @mermaid-js/mermaid-cli # .mmd support
# Optional for high-fidelity QA rendering:
# LibreOffice (soffice) + poppler (pdftoppm)
# Optional: pip install unoserver, then run `unoserver` in the background —
# render_slides.py auto-uses it (much faster repeated QA renders)

Smoke test (validate + build + QA on the example outline):

python3 scripts/smoke_test.py
pytest tests/