presentations

# Presentations `Presentations` is for serious, high-polish presentation work where "clean" is not enough. The target is an editable PowerPoint deck that feels like a strong editor, a strong analyst, and a strong designer built it together. Use this skill for analytics narratives, investor/operating reviews, strategy stories, product/business performance decks, and any PPTX task where the user asks to beat a reference deck. ## Operating Contract Use artifact-tool presentation JSX only. The bundled Codex runtime provides `@oai/artifact-tool` version 2.7.3 or newer and exposes `@oai/artifact-tool/presentation-jsx`. Do not require or import a separate presentation runtime package. PPTX export/render behavior must be accessed through artifact-tool. For template-following exact clone/edit mode, the production PPTX boundary is artifact-tool import of the duplicated starter PPTX and `PresentationFile.exportPptx(presentation)`. Do not use Python, direct OOXML package edits, LibreOffice save-as, or fresh-slide rebuilds to mutate the final template-following deck. For generated raster images or reference comps, use the Codex imagegen tool. Bundled scripts may write imagegen prompt files, but must not call external image APIs or read API keys. Thread-scoped paths: - `SKILL_DIR=<absolute path to the installed Presentations skill>` - `THREAD_ID=${CODEX_THREAD_ID:-manual-<timestamp-or-short-random-suffix>}` - `WORKSPACE=$PWD/outputs/$THREAD_ID/presentations/<task-slug>` - `SLIDES_DIR=$WORKSPACE/slides` - `PREVIEW_DIR=$WORKSPACE/preview` - `LAYOUT_DIR=$WORKSPACE/layout` - `ASSET_DIR=$WORKSPACE/assets` - `QA_DIR=$WORKSPACE/qa` - `OUTPUT_DIR=<user-provided output dir if any, otherwise $WORKSPACE/output>` - `FINAL_PPTX=$OUTPUT_DIR/<relevant-deck-title-slug>.pptx` Use absolute paths in commands and handoffs. Keep all generated planning text notes, preview PNGs, contact sheets, layout JSON, imagegen prompt files, temporary reference images, and other scratch files inside this thread-scoped `$WORKSPACE`. Keep only final deliverables in `$OUTPUT_DIR`. If the user provides an external output directory, write or copy only final deliverables there; generated `.txt` plans, contact sheets, previews, layout files, prompt files, and generated scripts must still stay under `$WORKSPACE`. Name the final PPTX with a short, relevant title derived from the deck topic or requested deliverable. Do not use generic filenames such as `output.pptx`, `deck.pptx`, or `deck.final.pptx`. Never use OS temp folders, a shared scratch folder such as `.presentation_workspaces`, `presentation-workspaces`, `presentation_workspaces`, `out`, or a bare repo-local deck slug unless the path is under `outputs/$THREAD_ID/presentations/`. If `CODEX_THREAD_ID` is unavailable, generate a manual id with timestamp plus a short random suffix. ## North Star The deck must win the contact-sheet test. At thumbnail size, it should show a coherent visual system, distinct slide rhythms, and evidence-led storytelling. At readable size, every slide should have a claim, a proof object, and no filler. This skill rejects "serviceable" output. A deck can pass layout checks and still fail. If it looks like a generic SaaS dashboard, consulting card grid, or autogenerated template after replacing the company name, keep iterating. ## Mandatory Workflow 1. Confirm the task mode. 2. Extract the source story. 3. Write the claim spine. 4. Lock the design system. 5. Plan the contact sheet. 6. Build editable artifact-tool slides. For template-following, import and edit the duplicated starter PPTX instead of rebuilding mapped slides from blank JSX; the starter script validates `template-frame-map.json` before duplication. 7. Render previews and layout JSON. 8. For non-template modes, score against the comeback rubric. 9. For non-template modes, iterate the weakest slides. For `template-following`, use the template-following QA loop in `$SKILL_DIR/profiles/template-and-edit.md`. 10. Export the final PPTX only after the rendered deck meets its task-specific QA gate. For `template-following`, the gate is source-slide fidelity, not reference beating, and includes the template fidelity guard in `$SKILL_DIR/profiles/template-and-edit.md`. 11. Clean up generated planning text notes, QA scratch files, contact sheets, preview images, generated slide modules/scripts, layout JSON, manifests, prompt text files, and other temporary images before the final response. ### Task Modes - `template-following`: user supplied a source/template deck whose slide skeletons and visual system must be inherited through exact clone/edit. Any attached PPTX clearly or implicitly presented as a template routes here - `create`: no deck/template is supplied; build from prompt and sources. - `targeted-edit`: small changes to an existing deck. For `template-following`, preserve the source deck's typography, palette, spacing, layout, and brand chrome unless the user explicitly asks to restyle. For `targeted-edit`, preserve the existing deck's visual system; use readability guidance only as a QA check for newly added or edited content. When both a source deck and a better reference deck exist, separate them: - source deck: content, required sections, facts, existing material. - reference deck: quality bar, rhythm, taste, and proof that a stronger output is possible. Template-like phrasing includes `template`, `follow this`, `use this style`, `same layout`, `corporate template`, `source deck`, or a filename/context that indicates a reusable template. Do not treat a template-like PPTX as a loose quality reference. For a non-template quality reference, do not blindly clone the reference. Beat it by improving story precision, composition variety, chart clarity, whitespace, and final render quality. ### Deck Profile Router After task mode, choose exactly one primary `deck-profile`. This is a hard routing step, not a labeling exercise. The profile determines which proof objects, source rules, visual density, asset rules, and QA gates are blocking. Profiles: - `finance-ir`: earnings, investor relations, operating reviews, financial analysis. Requires exact reported figures, unit discipline, source footnotes, bridges, tables, and disclosure logic. - `product-platform`: SaaS/platform/product narratives. Requires architecture maps, workflow diagrams, adoption proof, product-to-financial linkage, and no generic feature-card grids. - `gtm-growth`: GTM, marketing, consumer growth, subscription ecosystems, mobility, customer engagement. Requires a visible growth loop, segment or cohort proof, monetization bridge, and brand-aware rhythm. - `engineering-platform`: developer, AI, infrastructure, data, security, and technical platform decks. Requires accurate system diagrams, technical labels that survive executive simplification, and metrics tied to the architecture. - `strategy-leadership`: investor-day, board, transformation, and market strategy decks. Requires chapter discipline, market framing, strategic bets, and transition slides that carry the thesis. - `consumer-retail`: lookbooks, clienteling, luxury, consumer-brand, campaign, travel, lifestyle, food, fashion, beauty, people, places, animals, sports, playful/kids visual storytelling, and other image-led decks where the audience needs to visually inspect the subject. Requires real assets or explicit asset provenance, image quality, editorial hierarchy, and client-ready copy. - `template-following`: user supplied a template/source PPTX whose slides must be treated as the canonical editable starting point. This is exact clone/edit only: inspect the source slide inventory, map every output slide to a source slide, duplicate mapped slides, edit copied elements in place, and export via artifact-tool. Requires `template-audit.txt`, `template-frame-map.json`, and `deviation-log.txt`; follow `template-and-edit.md`. - `targeted-edit-data`: add or edit a data/comparison slide. Requires exact calculations before visual work and a native-looking insertion into the existing deck. - `targeted-edit-media`: add headshots, logos, screenshots, or other media. Requires identity/source verification, consistent crops, and preservation of the source deck layout grammar. - `appendix-heavy`: dense appendix, tables, disclosures, or source packs. Requires index/page markers, readable small-type thresholds, table grammar, and explicit source-density rules. If task mode is `template-following`, the execution path is always `template-and-edit.md`; add domain-specific profile gates such as `finance-ir` or `consumer-retail` as secondary constraints in the claim spine. For non-template tasks, if more than one profile applies, pick the profile that creates the highest delivery risk as primary, then list secondary gates in the claim spine. When a profile is selected, read its corresponding file under `$SKILL_DIR/profiles/` if the task is substantial or unfamiliar: - `finance-ir.md` - `product-platform.md` - `gtm-growth.md` - `engineering-platform.md` - `consumer-retail.md` - `template-and-edit.md` - `appendix-heavy.md` Create `$WORKSPACE/profile-plan.txt` with: - task mode - primary deck-profile - secondary profile gates, if any - required proof objects - source/asset requirements - brand authenticity constraints for logos, icons, mascots, screenshots, and other identity assets - profile-specific QA gates - known missing inputs ## Phase 0: Source And Reference Read For every source or reference deck: - Render it to PNGs or PDF pages. - Make a contact sheet. - Extract slide text. - Identify which slides are content sources, which are visual targets, and which patterns are anti-patterns. For source links: - Browse or otherwise retrieve the actual source page. - For finance/product narratives, exhaust official linked materials such as earnings decks, supplements, filings, and IR PDFs before omitting customer, cohort, module, bookings, retention, guidance, or mix metrics. - Extract exact metrics and source dates. - Keep links in source notes and in a quiet deck footer or appendix. - Never invent missing metrics to make a chart prettier. Brand authenticity gate: - Treat logos, mascots, app icons, product UI, character marks, badges, partner marks, and customer marks as identity assets. - Do not draw, trace, approximate, or stylize a company logo, mascot, app icon, or signature brand mark from scratch unless the user explicitly asks for an unofficial concept. - Use a verified source asset with provenance, use a user-provided asset, or omit the identity asset entirely. - When an official asset cannot be verified or embedded cleanly, rely on color, typography, layout, product language, and reported metrics as brand cues instead of inventing a pseudo-logo or decorative icon. - Record every identity asset in `$WORKSPACE/source-notes.txt` with source, provenance, and why it belongs in the deck. - For template-following and source-deck tasks, inspect which identity assets are official in the source. Preserve or borrow only verified assets; do not create lookalike marks to fill visual gaps. Create: - `$WORKSPACE/source-notes.txt` - `$WORKSPACE/reference-audit.txt` - `$WORKSPACE/data.json` when metrics/charts are used - `$WORKSPACE/template-audit.txt` for template-following or targeted-edit modes - `$WORKSPACE/template-frame-map.json` for template-following or targeted-edit modes - `$WORKSPACE/deviation-log.txt` when inheriting a source deck visual system - `$WORKSPACE/template-starter.pptx` when using a template PPTX as a starting point For template-following and targeted-edit modes, `template-audit.txt` must include: - preserve: visual rules that must survive - improve: weak spots that can be upgraded - do not imitate: source artifacts that should not be copied - brand/assets: logos, colors, imagery, type, and crop language - exact clone: typography, spacing, inherited placeholders, and source slide skeletons that must remain unchanged - insertion contract: how new slides or objects join the existing deck For template-following source slide inventory, duplicate-first starter deck creation, in-place copied-slide editing, and template QA blockers, follow `$SKILL_DIR/profiles/template-and-edit.md`. Do not use template codegen, generated template registries, source-PPTX visual-following rebuilds, or theme-matched fresh layouts for `template-following`. ## Phase 1: Narrative Spine Before designing, write the story as slide claims. This is binding. Every non-appendix slide must have: - a kicker: 1-3 words that names the role, e.g. `EXPANSION DRIVERS` - a claim title: a conclusion, not a topic label - a proof object: one chart, table, timeline, diagram, or visual comparison - a support note: concise, factual, and source-backed For finance/product narratives, a slide with only one thin chart usually fails. Prefer one dominant proof object plus a compact context rail, variance table, or callout stack when it improves the argument. Reject proof objects whose metric movement is too small to carry the claim unless they support a larger bridge. Product maps must show product-to-business linkage: module or workflow, adoption signal, expansion/monetization logic, or efficiency impact. Bad title: `Revenue and margin trends` Good title: `Growth slowed, but the margin engine kept expanding.` Bad title: `Expansion drivers` Good title: `Backlog is compounding faster than revenue.` If a title can be used after swapping the company name, sharpen it. Create `$WORKSPACE/claim-spine.txt` with: - thesis - audience - one-line arc - slide list with claim, proof object, source, and omission notes ## Phase 2: Design System Lock Create `$WORKSPACE/design-system.txt` before writing slide modules. The design system must define: - slide size, usually `1280x720` - background system - typography pair using installed fonts only - color palette with usage rules - chart grammar - diagram grammar - connector grammar - container / box grammar - source/footer grammar - page marker grammar - title/kicker grammar - data-label grammar - brand asset policy and identity-asset provenance - allowed brand cues versus forbidden logo/icon/mascot approximations - allowed layout families - banned motifs For `create` / from-scratch decks only, default to readable typography ranges: title `34-52px`, cover or section claims `56-72px`, body copy `18-26px`, chart/table labels and captions `12-16px`, and source/footer text `9-11px` only when it is not part of the core read. Define a three-color working palette: neutral/base, main accent, and secondary/support. Prefer monochrome plus accent or analogous plus contrast palettes over unrelated color collections. For `template-following` and `targeted-edit`, do not impose fresh typography or palette ranges. Record the inherited system and preserve it unless the user asks for restyling. For premium analytics decks, prefer: - warm paper or deep ink backgrounds, not default pale dashboards - a display serif or refined display face for claims - a utilitarian sans for labels - hairline rules instead of box outlines - open composition instead of repeated cards - direct labels on charts instead of heavy legends - fewer objects with stronger hierarchy - Kickers must align as one optical unit: marker center and label center share the same y-axis, and letter-spaced all-caps labels must be vertically centered in a box with enough breathing room to avoid low-looking baselines. - Use a canonical kicker construction rather than hand-tuning each slide: - marker and label must be named as a pair, e.g. `kicker-marker` and `kicker-label`, or `kicker-01-marker` and `kicker-01-label` - marker and label boxes should share the same vertical center within `<= 1px` - the label box must use middle vertical alignment and enough height to avoid low-looking glyphs after render/export - if multiple kicker rows appear on a slide, suffix the pair names consistently so QA can verify each row Do not use a one-note palette. Do not let teal, navy, beige, purple, or gray dominate without a deliberate secondary contrast. ## Phase 3: Contact-Sheet Plan Before building slides, create `$WORKSPACE/contact-sheet-plan.txt`. For a 10-slide deck, use at least 5 distinct macro-layout families, such as: - cover with metric rail - editorial product map - horizontal bar proof with margin notes - donut or mix proof with ranked evidence table - line chart with right-side KPI stack - sequential bar chart with side summary rail - two-series cash chart with margin callout - roadmap timeline - dense appendix table - dark appendix/source page Hard gates: - no more than 2 card-grid slides in a 10-slide deck - no 3 consecutive slides may share the same macro layout - no repeated `title + subtitle + boxed panel grid` cadence - no rounded card default unless the data relationship requires containment - no decorative boxes around prose The contact sheet must look authored before details are read. ## Phase 4: Editable Build For template-following mode, do not create fresh slides that imitate the source deck. Use the imported starter PPTX as the editable artifact-tool deck, mutate the duplicated source slides in place, then export the edited presentation: ```js const presentation = await PresentationFile.importPptx(await FileBlob.load(starterPptx)); // edit copied slides, shapes, tables, charts, images, and placeholders in place const pptx = await PresentationFile.exportPptx(presentation); await pptx.save(finalPptx); ``` Only use new slide modules and `presentation.slides.add()` for create / non-template work. A template-following output slide must come from a duplicated source slide; if no source slide can support the request, report the blocker and closest source slide options. Build one ESM slide module per slide in `$SLIDES_DIR`, exporting numbered functions such as: ```js export async function slide01(presentation, ctx) { const slide = presentation.slides.add(); // editable artifact-tool presentation JSX content return slide; } ``` Prefer native editable shapes, lines, text, tables, and chart-like constructs. For charts, native chart helpers are allowed, but authored editable chart systems built from shapes are acceptable when they give better label placement and visual polish. ### Structured Visual Precision Contract Charts, diagrams, connectors, boxes, tables, and flows are high-risk proof objects. Treat them as geometry systems, not decoration. Do not introduce new decorative custom SVGs, blobs, badges, ornaments, or icon-like shape stacks that do not encode data, hierarchy, or verified brand identity. In `template-following` or `targeted-edit`, do not strip inherited source-deck decoration solely because it is decorative. Before authoring any structured visual, define: - what the visual must prove - the primary reading order - each node / mark / series and what it means - each edge / connector and what relationship it encodes - each container / box and what grouping or containment it means - the intended alignment, spacing, and label attachment rules Hard build rules: - Connected series must be rendered as one continuous editable path or as a verified native chart series. Do not fake a line with separately rotated rectangles, disconnected strokes, floating slashes, or decorative arrows. - Every connected series must pass through its intended markers and preserve the correct point order after render/export. - In diagrams, connectors must visibly attach to the correct source and target, follow the intended direction, avoid unrelated objects, and terminate cleanly without ambiguous crossings. In JSX, use connector attachment props such as `fromElement`, `toElement`, `fromSide`, and `toSide`; in the shape API, use `slide.shapes.connect(from, to, ...)` rather than disconnected line segments. - Do not use arrows unless directionality matters. If direction matters, arrow heads must be consistent, legible, and semantically meaningful. - Boxes must imply a real grouping, comparison, lane, stage, or containment relationship. Remove containers that only decorate prose. - Equal-role boxes must share exact height, alignment, padding, border logic, and text treatment unless the hierarchy intentionally differs. - Text inside boxes must have enough padding and never sit against edges, collide with rules, or rely on shrink-to-fit as the default. - Use a minimum `12px` vertical interior padding for boxed prose / callouts and `16px` when the box carries 2+ lines or dark-background copy. If a box only looks correct with near-zero bottom room, enlarge the box or shorten the copy. Map this to the authoring surface: JSX layout boxes can use `padding`; imported or shape text should use `shape.text.insets`; paragraph spacing should use `spaceBefore` / `spaceAfter`, not manual spacer shapes. - Any text that starts inside a filled callout / metric container and spills past that container edge is a hard failure, even if the overflowed line is no longer classified as an in-box child by a layout script. - Labels must anchor to the mark, series, box, or connector they describe. A viewer should never need to guess which label belongs to which object. - Repeated metric rails / KPI stacks must preserve their full grammar on every item: if the pattern is `value + label + context`, every item must visibly render all three pieces with adequate contrast against its background. - Preview-visible defects override layout-script silence: orphan labels, missing values in a repeated metric pattern, markers sitting on top of copy, or any object that looks obviously accidental at full size must be treated as a build failure even when export and layout checks succeed. - Tables and matrices must preserve row/column grammar under thumbnail review: headers, baselines, alignment, and emphasis must remain visually consistent. - If a chart or diagram requires too many exceptions to remain clear, rebuild it with a simpler visual rather than patching around geometry defects. artifact-tool presentation JSX chart caveat: - Try native `slide.charts.add(...)` when the API can represent the chart. - Do not style `chart.yAxis.majorGridlines` unless freshly verified; it can fail export with `this[#h].toProto is not a function`. - Do not fake per-point bar colors by adding zero-valued helper series. If native charts cannot express the visual cleanly, rebuild the chart with editable shapes and direct labels. - For line, trend, or connected-series visuals, prefer a verified native line chart when the API can express the chart cleanly. If authored with primitives, draw the series as one continuous editable custom path / polyline through the data points. - Do not construct a line series from individually rotated rectangles or short segment shapes; these can export as detached slashes or broken pseudo-arrows. - Record the choice in `$WORKSPACE/qa/comeback-scorecard.txt`. Use helper scripts copied with this skill: ```bash