Skill definition

hi-pptx

Create, edit, and visually validate client-ready PowerPoint presentations (.pptx) using a sanitized navy-white-orange-teal design system, with evidence-led storylines, natural executive copy, editable architecture/process/timeline/option layouts, and professional native charts derived from supplied CSV, JSON, spreadsheet, or tabular data. Use for executive proposals, consulting decks, technical architecture, current-state assessments, phased roadmaps, investment options, KPI reviews, and Japanese-customer-facing presentations where visual consistency, quantitative accuracy, privacy, and presentation readiness matter.

Planning Architecture

SKILL.md

Client-ready presentation engine

Create calm, credible executive PowerPoint decks from a sanitized, text-only design specification. Use editable PowerPoint elements, including native charts, rather than flattened screenshots. Do not retain or depend on confidential reference presentations.

Required resources

Read only the resources needed for the request:

Always read references/reference-template.md for the sanitized design tokens, layout archetypes, and placement rules.
Read references/writing-and-storyline.md for audience, storyline, titles, evidence language, and the anti-buzzword voice gate.
Read references/data-visualization.md whenever numeric data, KPIs, charts, comparisons, trends, distributions, or forecasts are involved.
Read references/quality-review.md before final QA.

No original reference deck or rendered preview is bundled. Do not search for, reconstruct, or reuse confidential source content. Use only the sanitized rules documented in this skill and assets explicitly supplied for the current request.

Non-negotiable outcomes

Story and evidence:

Define the audience, decision, and central takeaway before selecting layouts.
Give every slide one narrative job and a conclusion-led title.
Preserve source meaning and distinguish provided facts, calculations, assumptions, illustrative examples, and unknowns.
Never invent metrics, quotations, case studies, customer claims, or sources.
Put external sources and calculation definitions in speaker notes.

Visual system:

Use the navy-white base with orange emphasis and restrained teal, green, purple, blue, or gold support colors.
Select from five sanitized layout archetypes before inventing a new composition: architecture, current-state assessment, workflow, phased roadmap, and options.
Apply consistent typography, spacing, headers, footers, alignment, and panel geometry from references/reference-template.md.
Use authentic brand assets only when the user supplies or authorizes them.
Keep charts, tables, diagrams, and timelines editable.

Data integrity:

Compute first, design second. Validate units, denominators, time grain, missing values, sorting, totals, and rounding before charting.
Choose a chart from the analytical question, not decoration preference.
Highlight one decision-relevant series or point; keep the rest subordinate.
Never declare completion before rendering and inspecting every slide.

Intake

Confirm or infer only when low-risk:

Audience and decision makers.
Meeting objective and expected decision or action.
Speaking time and likely slide count.
Language, tone, and localization needs.
Source-of-truth files, data definitions, and confidentiality constraints.
Whether supplied brand assets should be applied or the deck should remain unbranded.

Ask only when missing information could materially change claims, data interpretation, branding, or storyline. Otherwise proceed with an explicit assumption register.

Workflow

1. Establish the communication job

Write one sentence in the form: by the end, the audience should take an action or reach an understanding because of the central takeaway. Build an evidence map:

Provided fact: directly traceable to user material.
Derived statement: faithful synthesis or reproducible calculation.
Assumption: necessary but unverified; label it.
Illustrative: fictional example or placeholder; label it visibly.
Unknown: leave as a question, dependency, or TBD.

2. Inspect inputs and select the visual system

Inventory all inputs and identify the authoritative version.
Run scripts/analyze_pptx.py on a user-supplied deck to capture slide size, layouts, fonts, colors, density, and object counts.
If the user supplies a template, follow that template and preserve its master -> layout -> slide hierarchy.
Otherwise use the sanitized system in references/reference-template.md as an explicit custom visual direction and build the deck from scratch.

3. Plan the narrative and layout map

For every output slide define:

Field	Required content
Narrative job	Why the slide exists
Takeaway title	The conclusion the audience should retain
Evidence	Facts, calculations, visuals, or explicit assumptions
Layout archetype	Architecture, assessment, workflow, roadmap, or options
Content zones	Exact bounded areas for text, charts, tables, or diagrams
Transition	Why the next slide follows

Every output slide must map to an archetype or document a reason for a custom layout. Shorten copy, change archetypes, or split the content instead of shrinking text or adding unplanned overlays.

4. Profile data and select the chart

When tabular data is supplied:

Extract a clean CSV or JSON table without altering source values.
Run scripts/profile_chart_data.py <input> --output <profile.json>.
Review inferred types, missing values, duplicate categories, numeric ranges, totals, and suggested chart families.
Confirm the intended analytical question and units. A script suggestion is evidence for selection, not an automatic design decision.
Read references/data-visualization.md and build an editable native chart in an approved chart zone.
Reconcile every plotted value and displayed label with the clean table.

If the data cannot support the requested conclusion, say so and use a table, question, or data-gap slide instead of forcing a chart.

5. Implement the deck

Use JavaScript ES modules and @oai/artifact-tool for PowerPoint authoring.
Use a 16:9 canvas and central design tokens for colors, typography, margins, title bands, key-message rails, panels, and footers.
Build reusable helper functions for the five sanitized archetypes rather than copying confidential slides.
Keep title and body copy inside the bounded zones documented in references/reference-template.md.
Use native slide.charts.add(...) charts. Do not use Python-PPTX, PptxGenJS, or raster chart screenshots for authoring.
Preserve or add [Sources] blocks in speaker notes for non-trivial claims, data, and externally sourced assets.

6. Apply chart quality gates

Use navy #1F3864 for the primary series, orange #F37021 for the single decision-relevant highlight, and teal #127E84 or green #1E9E54 for a secondary series.
Prefer direct labels. Use a legend only when direct labeling would clutter.
Start bar-chart value axes at zero. State any necessary non-zero baseline.
Avoid 3D, decorative gradients, dual axes, rainbow palettes, tiny labels, and pie/doughnut charts with many slices.
Add units to axes or labels and include source, period, scope, and denominator in notes or a compact footer.
Use a takeaway title that states the computed result, not a generic topic.

7. Preflight and visual QA

Run the bundled checks from the skill directory:

python scripts/lint_pptx.py output.pptx --output qa/lint.json
python scripts/render_pptx.py output.pptx --output-dir qa/rendered --cols 4

Then:

Review the generated contact sheet for narrative rhythm, repeated silhouettes, and density.
Inspect every slide individually at full size.
Fix clipping, overflow, awkward wrapping, unintended overlaps, inconsistent footers, broken connectors, unresolved placeholders, and chart/data mismatches.
Re-render the complete deck after fixes and repeat until clean.

Automated checks are triage, not proof of quality. Do not waive a visual defect without inspecting it and recording a valid reason.

Deliverables

Return:

The final .pptx.
A short summary of storyline, layout archetypes, and chart choices.
Any unresolved assumptions, missing evidence, or editable placeholders.
The generated contact sheet only when it helps the user review the deck.

Bundled resources

references/reference-template.md: sanitized design tokens, layout archetypes, placement rules, and bounded chart zones.
references/data-visualization.md: question-to-chart routing, native chart recipes, statistical integrity, and QA.
references/writing-and-storyline.md: executive narrative and natural copy.
references/quality-review.md: voice, visual, privacy, and completion gates.
scripts/profile_chart_data.py: profile CSV/JSON and suggest chart families.
scripts/analyze_pptx.py: inspect structure without reproducing slide text.
scripts/lint_pptx.py: flag layout, density, type, and writing issues.
scripts/render_pptx.py: render every slide and build a contact sheet.

Example invocations

“Use $hi-pptx to turn this assessment into a six-slide client proposal. Keep the facts unchanged and do not retain confidential inputs.”
“Use $hi-pptx to chart this CSV, explain the strongest trend, and create an executive KPI review with editable native PowerPoint charts.”
“Use $hi-pptx to build a technical architecture and phased roadmap using the sanitized corporate visual system.”

wiki/en/hi-pptx-skill.md

Wiki guide

Hi PPTX Skill: Complete Guide

hi-pptx is a presentation engine that creates, edits, and visually validates client-ready PowerPoint decks using an evidence-driven storyline, native editable charts, a sanitized light design system, and strict quality gates.

1. Objective

The skill serves:

executive proposal;
consulting deck;
architecture/current-state assessment;
phased roadmap;
investment options;
KPI review;
technical presentation;
Japanese-customer-facing deck.

It does not just produce a .pptx. It must simultaneously ensure:

clear audience and decision;
each slide has one narrative job;
claims traceable;
data computed correctly before design;
charts/diagrams editable;
consistent visual hierarchy;
render and inspect every slide before completion.

2. Hard outcomes

Story and evidence

identify audience, decision, central takeaway;
each slide has a conclusion-led title;
distinguish fact, calculation, assumption, illustrative, unknown;
do not invent metrics/quotes/cases/sources;
external sources/calculation definitions in speaker notes.

Visual system

white/light canvas, dark structural ink, restrained accent;
choose a layout archetype before custom composition;
typography/spacing/panels consistent;
charts/tables/diagrams editable;
brand assets only used when supplied/authorized.

Data integrity

compute first, design second;
validate unit, denominator, period, missing values, totals, rounding;
chart per the analytical question;
highlight one decision-relevant series/point;
do not declare complete before rendering/inspecting every slide.

3. Overall workflow

Loading diagram…

4. Intake

Determine or ask when low-risk:

audience/decision makers;
meeting objective and decision/action;
speaking time/slide count;
language/tone/localization;
source-of-truth files/data definitions/confidentiality;
whether brand assets may be applied.

Only ask when missing information would change:

claims;
data interpretation;
branding;
storyline.

Otherwise, use an explicit assumption register.

5. Communication job and evidence map

Write one sentence:

By the end, the audience should [action/understanding] because [central takeaway].

Evidence map:

Label	Meaning
Provided fact	Directly traceable from input
Derived statement	Synthesis/calculation reproducible
Assumption	Needed but not yet verified
Illustrative	Fictional/example, must be labeled
Unknown	Reserved for questions/dependencies/TBD

Do not fill a hero number with a fabricated metric. If data is missing, use a question/appendix.

6. Storyline

Common sequence:

Context → Observed issue → Implication → Proposed response → How it works → Plan → Risks/assumptions → Decision/next step

Do not force the sequence if the meeting objective differs. Each slide has one primary purpose:

orient;
explain;
compare;
diagnose;
recommend;
decide;
plan;
confirm.

Takeaway title

The title is a conclusion/observation, not a category label.

weak: Current Situation;
good: Three waiting steps slow every response.

Titles should be one line, around <=35 characters per the design system or <=12 words/70 Latin characters per the writing guide, whichever layout constraint is tighter.

Body blocks are at most 30-40 words; put the key point first; avoid buzzwords, cloned bullets, and slogans.

7. Visual system

7.1 60-30-10 light rule

60% canvas: white #FFFFFF or pearl #F8FAFC;
30% structure: dark #0F172A/#000000;
10% accent: one hue such as indigo, crimson, or burnt orange.

One deck picks exactly one palette; do not mix palette A/B.

7.2 Palette A: Crisp Swiss

background #FFFFFF;
card #F1F5F9;
primary #020617;
secondary #64748B;
accent #4F46E5 or #059669;
border #E2E8F0.

7.3 Palette B: Warm Editorial

background #FDFBF7;
card #F3F0E6;
primary #1C1917;
secondary #78716C;
accent #EA580C or #DC2626;
border #E7E2D8.

7.4 Hero element

Each slide has exactly one focal hero:

giant metric;
key quote;
featured tile;
stark contrast block.

If two elements compete, move one to another slide/appendix/notes.

7.5 Swiss grid

canvas 1280×720 px, 16:9;
12-column grid;
padding 60px top/bottom, 80px left/right;
at most 2-3 content blocks;
one quiet zone;
hairline or one soft shadow, never both on the same card;
card radius 16px.

8. Layout archetypes

Layout	Use for	Rules
Hero Metric	KPI/headline stat	One giant number, whitespace
Stark Editorial Split	Takeaway/chapter	50/50, one contrast block
Tiled Comparison	Framework/strategies	At most 3 tiles, one featured
Bold Statement	Quote/vision	One oversized statement, attribution

Support layouts for roadmap, architecture, matrix, risk register while keeping the palette, hierarchy, and one-highlight rule.

Do not force dense content into a hero layout. Split the slide or move details to the appendix.

9. Typography and accessibility

title geometric sans, weight 700/800;
body readable sans;
body .pptx text no smaller than 14pt;
footnotes/sources at least 9pt;
titles/bodies do not overflow;
Vietnamese/Japanese glyphs render correctly;
font substitution is a defect that must be verified;
contrast reading text >=4.5:1;
do not use color alone to encode meaning.

Font fallback must be cross-platform; SF Pro Display cannot be embedded/redistributed, so use Helvetica Neue/Inter/Arial/Aptos as appropriate.

10. Data workflow

When CSV/JSON/table data is available:

preserve clean source table;
profile with scripts/profile_chart_data.py;
check grain, unit, currency, denominator, period, timezone;
find missing/duplicate/suppressed/estimated/outlier;
recalculate totals/shares/deltas/rates;
define rounding after calculation;
choose the chart per the analytical question;
build native chart;
reconcile plotted values with the clean table.

Do not force a chart if the data does not support the conclusion; use a table/question/data-gap slide.

Chart routing

Question	Chart
Trend over time	Line
Category ranking	Horizontal bar
Few categories over time	Column
Composition	100% stacked bar
Contribution to change	Waterfall
Actual vs target	Bar/bullet
Relationship	Scatter
Distribution	Histogram/box
Single decision metric	KPI + small trend
Precise values	Table

Avoid 3D, rainbow, decorative charts, >5-slice doughnut, unjustified dual-axis.

Chart styling

primary navy #1F3864;
one highlight orange #F37021;
secondary teal #127E84/green #1E9E54;
direct labels when possible;
zero baseline for bars;
units/period/source/denominator in notes/footer;
native editable slide.charts.add(...).

11. Implementation

Native PPTX

use JavaScript ES modules;
use @oai/artifact-tool;
16:9 canvas;
central design tokens;
reusable helpers per archetype;
native charts, not raster screenshots;
[Sources] blocks in notes.

HTML/CSS route

Can be used for browser decks, PDF export, or prototypes:

canvas 1280×720;
CSS variables as source of truth;
self-contained font fallback;
same palette/layout rules;
rebuild to an editable PowerPoint when the deliverable is a .pptx.

Inputs

If the user provides a deck/template:

run analyze_pptx.py;
inspect size/layouts/fonts/colors/density/object counts;
preserve master → layout → slide hierarchy;
do not reconstruct confidential source content.

12. QA and completion gate

Automated preflight:

python scripts/analyze_pptx.py output.pptx --output qa/analysis.json
python scripts/lint_pptx.py output.pptx --output qa/lint.json
python scripts/render_pptx.py output.pptx --output-dir qa/rendered --cols 4

Completion only when:

the .pptx opens successfully;
lint has no remaining unresolved errors;
every warning is fixed or explicitly justified;
every slide rendered;
contact sheet reviewed;
every full-size slide inspected;
voice gate and template-fidelity gate pass;
any subsequent corrections have been fully re-rendered.

Loading diagram…

Automated lint is triage, not proof of visual quality. Do not waive a visual defect without inspecting it.

13. Voice gate

Check every title/body:

no forbidden buzzwords/slogans;
headline is a conclusion;
title is one line;
bullets are not cloned skeletons;
no generic marketing claims;
quotes have real attribution;
hero numbers are traceable or labeled.

14. Template-fidelity gate

Every slide:

clear primary read;
navy hierarchy, orange only for the main decision point;
maps to an archetype;
title/key-message/footer/alignment correct;
at most 3 main options;
one recommendation highlight;
chart in the bounded zone;
sufficient contrast;
white text only on dark/accent fields with sufficient contrast.

15. Visual review

Contact sheet

Check:

beginning/middle/end;
section transitions;
consecutive density;
mechanical composition repetition;
important slides stand out;
accent not becoming wallpaper;
final slide supports the outcome.

Full-size