Skip to content

SKILL.md

Latest commit

 

History

History
498 lines (361 loc) · 22.9 KB

SKILL.md

File metadata and controls

498 lines (361 loc) · 22.9 KB
name pptx-from-html
description Design presentations in HTML first, then compile to PPTX. Use this skill whenever the user wants to create a slide deck, pitch deck, or presentation — whether from scratch or modifying an existing one. Triggers on mentions of "slides", "deck", "presentation", "pptx", "keynote", "pitch deck", "slide design", or requests like "make me a presentation about", "create slides for", "I need a deck", "help me with my presentation". Also applies when the user says "restyle my slides", "make this deck look better", or "redesign this presentation". For simple edits to an existing PPTX (typo fixes, number updates), may delegate directly to the pptx skill. For anything involving visual design, content strategy, styling, or creating more than a couple slides — this skill drives the process through HTML-first design. Key insight: HTML is where AI is strongest visually — iterating on layout, color, typography in real time. The pptx skill is just the compiler. Don't skip the HTML design phase.

pptx-from-html

Create presentations by designing in HTML first, then compiling to PPTX.

HTML is where the thinking happens — content structure, visual style, layout, typography. PPTX is the delivery format. This skill treats the pptx skill as a compiler: you design in HTML, iterate until it's right, then compile once.

Dependencies

This skill orchestrates two other skills that must be installed:

  • brainstorming — drives the content and style discovery conversations
  • pptx — compiles the final HTML-approved design into a .pptx file

If either is missing, stop and tell the user:

"This skill requires the brainstorming and pptx skills to be installed. Please add them to your skills configuration before continuing."

Additionally, if the content involves diagrams or visual assets, the drawing-in-html skill (from this same repo) is strongly recommended.

For source document conversion (PDF, DOCX, PPTX, HTML, EPUB to Markdown):

  • markitdown — Microsoft's universal document-to-Markdown converter
    • pip install markitdown==0.1.4

The Complete Flow

Content Brainstorming → Style Brainstorming → Creating (HTML) → Compile (PPTX) → Self-Review → Human Review

Each phase is a conversation with the user. Every phase loops until the user is satisfied before moving to the next. At any point, the user can request going back to an earlier phase.

Phase 1: Content Brainstorming

Goal: Agree on what the presentation says. Output: a finalized Markdown document.

Source document conversion

If the user provides a source document (PDF, DOCX, PPTX, HTML, EPUB), convert it to Markdown first using markitdown:

markitdown source-document.pdf > content-raw.md

This works for PDF, DOCX, PPTX, XLSX, HTML, EPUB, images, and more — one tool for all source formats.

Content brainstorming

Invoke the brainstorming skill to drive this conversation. Work with the user to define:

  • The story arc — what's the narrative?
  • Slide structure — what slides exist, what each one communicates
  • Key messages per slide
  • Supporting data, diagrams, or visuals needed

Diagrams and visual assets

If any slide needs a diagram, chart, architecture visualization, or any drawn visual:

  • Hint to the user: "This slide calls for a diagram. Want me to use the drawing-in-html skill to create it?"
  • If yes, invoke drawing-in-html to collaboratively design the visual
  • Generate at least 2× resolution images (PNG export at scale 2) for every visual asset. Presentation projectors and retina screens demand high-res images — 1× will look blurry.
  • Keep the source HTML alongside the exported PNGs for future editing

Unlimited rounds. Keep iterating until the user is happy with the content.

Output: A Markdown file (content.md or similar) that captures the agreed content for every slide — including references to any diagram/image assets created. This is the contract — style work builds on top of this, not around it.

Always generate this Markdown as the final artifact of Phase 1 before moving on.

Phase 2: Style Brainstorming

Goal: Agree on how the presentation looks. Output: a single chosen visual style.

This is visual brainstorming — done entirely in HTML.

Starting point: user references

Before generating anything, ask whether the user has visual references. This is one of the biggest advantages of the HTML-first approach — any reference can be absorbed:

  • A screenshot of a website they like the feel of
  • Someone else's presentation they admire
  • A poster, magazine spread, or album cover
  • A brand style guide or color palette
  • Even a vague direction ("something that feels like a museum exhibit" or "Wes Anderson")

If provided, analyze the reference and extract: color palette, typography character, layout density, decorative vs. minimal, light vs. dark, the overall mood. Use these as a starting constraint for the exploration — not a single answer, but a center of gravity around which to generate variations.

If the user has no reference, start broad.

Style must serve the content

Read the content Markdown from Phase 1 before designing anything. The content's audience, tone, and subject matter must visibly influence every style option.

Not all styles work for all content. A quarterly business review should not use pixel art or cyberpunk aesthetics. A creative pitch should not use stiff corporate grids. Consult the Content-Style Matching section in references/slide-design-styles.md for specific guidance on which styles fit which contexts, and which combinations to avoid.

The style exploration page

Always present all styles on a single HTML page so the user can compare at a glance. Separate files for each style defeat the purpose — the power is in side-by-side comparison.

Page format:

  • Grid layout, 4 columns on desktop
  • Each style is a card containing a name/label and thumbnail-sized slide renderings
  • Show 2 representative slides per style — the title/cover slide and a data-heavy or content-heavy slide. These two pages exercise different layout needs and reveal whether a style works beyond just a pretty cover.
  • Each mini-slide renders at 16:9 aspect ratio within the card

Aim for 15–20 genuinely different styles. More is better in round one. People's taste is hard to articulate in advance, and early in the process, the most productive thing you can do is show a wide range so the user can react ("yes, like that" / "not that"). Most will get cut — that's the point. They calibrate what the user actually wants.

What "genuinely different" means

A color swap is not a different style. Changing navy to forest green produces the same design in a different color. Genuinely different means different design language — each style should feel like it was made by a different designer from a different era or discipline.

Vary along structure, typography, color mood, and design language simultaneously. Read references/slide-design-styles.md for the full axis breakdown — it covers 26 styles (conventional + art movements), layout patterns, typography rules, color palettes, and content-style matching guidance. Use it as a launching pad, not a boundary. Combine categories, invent new ones, go in directions not covered at all.

Professional design principles

Spend real effort here. Each style should look like it was crafted, not generated.

Common pitfalls to avoid:

  • Accent lines under titles (hallmark of AI-generated slides)
  • Generic gradient backgrounds with white text (looks like a template)
  • Color swaps disguised as different styles
  • Decorative elements that don't serve the content
  • Styles that fight the content's tone (playful visuals on serious data)

Narrowing down

Ask the user: "Which styles do you want to keep? Which should go? Any new directions you'd like to see?"

Expect multiple rounds. Real style exploration rarely converges in one pass. The typical pattern:

  1. Round 1: User kills half, keeps half, maybe requests new directions
  2. Round 2: Replace killed styles with new options, user reviews the updated set
  3. Round 3+: Repeat until the user has ~3–5 strong candidates

When the user kills a style, try to understand why. "Too generic" means push harder on distinctiveness. "Doesn't fit" means revisit the content-style match. "Boring" means more art-direction courage. Replace killed styles with options that address the underlying feedback, not just random alternatives.

Once narrowed to ~3 finalists, show those at fuller fidelity (more slides rendered, larger size) and ask the user to pick one.

Unlimited rounds. There is no cap on how many times you iterate on style.

Phase 3: Creating (HTML)

Goal: Generate the full deck as HTML, every slide, in the chosen style.

Render every slide from the content Markdown in the selected style as HTML. Present it as one HTML page — sections represent slides — so the user can review the full deck in the browser.

Image handling

All images and diagrams embedded in slides must:

  • Use at least 2× resolution source files (generated via drawing-in-html or other tools)
  • Be constrained to fit their slide area without stretching or distortion — use object-fit: contain or equivalent, never stretch/fill
  • Maintain their original aspect ratio at all times
  • Be sized proportionally to the slide — a diagram shouldn't dominate when it's supporting detail, nor be tiny when it's the main point

Ask the user to review. At this point, feedback may go in different directions:

  • Content changes → go back to Phase 1, update the Markdown, then re-render
  • Style changes → go back to Phase 2 for further exploration
  • Slide-level tweaks → adjust specific slides in place (layout, emphasis, spacing)
  • Happy → move to Phase 4

Iterate until the user says the HTML deck looks right.

Phase 4: Compile to PPTX

Always invoke the /pptx skill for compilation. Do not write PptxGenJS code directly — the pptx skill handles that. This skill designs; the pptx skill compiles.

The pptx skill is a compiler. It does not make design decisions.

The HTML is the definitive, pixel-level reference. When invoking the pptx skill, be explicit:

"Compile this HTML deck into PPTX. The HTML is the exact specification — match it precisely. Same layout, same typography, same colors, same spacing, same content, same image sizes and positions. Do not add, remove, or restyle anything. Do not apply default templates. The HTML IS the template."

If the pptx skill's output deviates from the HTML (different fonts, spacing, colors, element positions), that's a bug to fix — not a "style choice."

Image fidelity in PPTX: When embedding images in the generated PPTX, ensure:

  • Images are inserted at their native resolution (the 2× exports), not downscaled
  • Aspect ratio is preserved — never stretch to fill a placeholder
  • Images are positioned and sized to match the HTML layout

CSS effects that need image workarounds

Some CSS effects cannot be replicated natively in PPTX:

  • repeating-linear-gradient patterns (hatching, stripes, textures)
  • radial-gradient atmospheric effects (ink wash, glow, paper texture)
  • mix-blend-mode color overlays
  • Complex background-image layering

The workaround: Render the effect in a standalone HTML file, screenshot it to PNG with Playwright, and use the PNG as a slide background or image element in the PPTX. This preserves the exact CSS rendering. Create separate PNGs for each variant (e.g., cream-with-hatching, red-with-hatching, black-with-hatching for different cell colors).

The SVG-to-PNG technique for visual fidelity

PptxGenJS cannot faithfully reproduce many visual effects: hard offset shadows, complex borders with rounded corners, rotated decorative shapes, gradient overlays. When the HTML design uses effects that PptxGenJS will get wrong, use this technique:

  1. Design the element as SVG (or HTML/CSS) — the visual you want, exactly
  2. Render to transparent PNG at 2× resolution via Playwright (omitBackground: true)
  3. Place the PNG in the slide as an image element at the correct position
  4. Add a native text box on top for any editable text within that element

Always do this per element, not per slide. Never render an entire slide as one big image — that destroys editability. Each card, decorative shape, badge, or icon gets its own small transparent PNG. A slide might have 4-8 individual PNG elements plus native text boxes. This keeps everything individually selectable, movable, and resizable in PowerPoint — so users can adjust layout without regenerating the deck. Only use this technique when PptxGenJS can't match the HTML — simple rectangles, text, and lines should still be native PptxGenJS shapes.

Never embed SVG directly in PPTX. PowerPoint (especially on Mac) renders SVG images unreliably — elements may disappear or display incorrectly. Always render SVG to PNG first.

Common effects that need this approach:

  • Hard offset box-shadows (PptxGenJS only does blurred shadows)
  • CSS repeating-linear-gradient patterns (hatching, stripes, textures)
  • radial-gradient atmospheric effects (ink wash, glow, paper texture)
  • mix-blend-mode color overlays
  • Rotated shapes with borders and shadows
  • Complex border-radius + shadow combinations

Phase 5: Self-Review

Assume there are problems. The first compile is almost never correct. Approach this as a bug hunt, not a confirmation step.

Always use the /pptx skill's QA process. Follow its QA section — it handles converting slides to images and provides the inspection prompt for subagents. Use subagents for fresh-eyes inspection — don't review your own work without fresh eyes. Always compare the PPTX renders against the HTML reference screenshots side by side.

Content check (per slide)

Compare against the content Markdown:

  • Text matches the agreed content — no placeholders, TODOs, or missing data
  • All numbers, names, and data points are accurate
  • No leftover template text from the pptx skill

Visual check (per slide)

Compare against the approved HTML reference:

  • Typography matches — same fonts, sizes, weights (the pptx skill often substitutes)
  • Colors are correct — no accidental defaults or off-palette colors
  • Spacing and alignment match — margins, padding, element positions
  • Images appear at correct size without stretching or distortion
  • Visual hierarchy is clear — Duarte's Glance Test: can you grasp the point in 3–5 seconds?

Common PPTX compilation failures to specifically hunt for:

  • Overlapping elements — text bleeding through shapes, stacked elements
  • Text overflow — cut off at slide edges or box boundaries
  • Low-contrast elements — light text on light backgrounds, dark on dark
  • Insufficient margins — elements too close to slide edges (< 0.5")
  • Uneven spacing — large empty areas next to cramped sections
  • Font substitution — the pptx skill silently swapping to a default font

Deck-level check

  • Style is uniform across all slides — no odd-one-out slides
  • Narrative flows coherently from first slide to last

Fix issues silently. Don't ask the user about self-review findings — just fix them. If fixes require changes to the HTML or content, update those sources, recompile, and re-review. One fix often creates another problem — keep iterating until a full pass reveals no new issues.

Phase 6: Human Review

Present the compiled PPTX to the user for final review.

If the user requests changes, judge which phase to return to:

  • "Change the messaging on slide 3" → Phase 1 (content)
  • "I want a completely different look" → Phase 2 (style)
  • "Make the title slide more impactful" → Phase 3 (creating, slide-level tweak)
  • "The diagram on slide 5 is blurry" → Phase 3 (re-export at higher resolution)
  • "Looks great, ship it" → Done

Modifying an Existing Presentation

Not every request is a brand-new deck. When the user wants to modify an existing PPTX:

Triage first

Is this a small edit? Examples: fix a typo, update a number, add one slide, change a color.

→ Skip the full flow. Use the pptx skill directly to make the edit. Then do self-review (Phase 5) → human review (Phase 6). Done.

Is this a big change? Examples: restyle the whole deck, restructure the narrative, add many slides, "make it look more professional."

→ Treat the existing PPTX as input:

  • Extract content with markitdown existing.pptx > content-raw.md
  • Extract the current visual style as one reference point for Phase 2
  • Run the full flow from whichever phase applies

When in doubt, ask the user what scope of change they're looking for.

Key Principles

  • HTML is the design medium. All visual decisions are made in HTML. PPTX is compilation.
  • Markdown is the content contract. Always produce a Markdown file as the content agreement before moving to style work.
  • Styles serve the content. Never apply generic templates — every style must be designed for the specific content, audience, and tone.
  • Images at 2× minimum. Every visual asset is exported at double resolution. Images in slides must never be stretched or distorted.
  • Unlimited rounds. Never rush the user through phases. The point is to get it right.
  • Go back freely. The phases aren't a one-way pipeline. Users can always revisit earlier decisions.
  • Judge the right re-entry point. When changes are requested, figure out which phase to return to rather than starting over.
  • Self-review after compilation. Review the actual PPTX, not just the HTML. Check every slide visually and for content accuracy.
  • Per-element PNG for visual fidelity. When PptxGenJS can't match an effect, render it as SVG → transparent PNG and place it individually. Never SVG directly in PPTX, never one big image per slide.

Gotchas

Hard-won lessons from real usage. Add to this list as new failure modes emerge.

  • Separate HTML files per style kills the exploration. The user can't compare styles they can't see side-by-side. Always put all styles on one page. If you generate 20 separate files, the user has to open 20 browser tabs and flip between them — they'll hate it and the feedback will be worse.

  • "Different color" ≠ "different style." The #1 failure mode in style exploration. Changing the accent from blue to coral is not a new style. Each option must feel like it was designed by a different person from a different design tradition. If you find yourself reaching for a new hex code instead of a new design concept, stop.

  • Warm earthy palettes all look the same at thumbnail size. Terracotta, sand, sage, cream — they converge visually when rendered small. If you include more than one warm/earthy style, make them structurally different (e.g., one uses asymmetric layout, the other uses strict grids with heavy borders).

  • Style-content mismatch is immediately obvious. A pixel-art Q2 business review or a cyberpunk investor update is not "creative" — it's tone-deaf. Before designing, ask: "Would someone actually present this to the intended audience?" If the answer is "only as a joke," cut it.

  • Users don't converge in one round. The skill used to say "narrow to 3 finalists." In practice, users kill some, keep some, request new directions, and need 2-3 rounds of replacement before they have a final set. Design the interaction for iterative kill/keep/add cycles, not a single funnel.

  • "More effort" means more art direction, not more CSS. When a user says the styles look generic, the fix is to draw from richer design traditions (Constructivism, Ukiyo-e, Film Noir, Letterpress), not to add more gradients or box-shadows.

  • The cover slide is necessary but not sufficient. A style that only looks good on the title slide is useless. Always show at least the cover + a data-heavy slide in the exploration. Data slides reveal whether a style actually works or just has a pretty face.

  • Don't forget to ask for references. Users often have a screenshot, a website, or a poster in mind but won't volunteer it unless asked. One good reference image saves 2 rounds of style iteration.

  • CSS patterns don't survive PPTX compilation. Repeating gradients, diagonal hatching, paper textures, halftone dots — none of these translate to PPTX natively. The workaround: render the pattern in HTML, screenshot it to PNG, and use the PNG as a slide background image. This preserves the exact CSS output. See the examples/q2-report/assets/ directory for a working example.

  • Low-opacity elements render darker in PPTX. An element at 4% opacity in CSS will render at ~10-15% equivalent in PPTX. Compensate by setting pptxgenjs transparency values 3-5 points higher than you'd expect from the CSS.

  • CJK + Latin text gets extra whitespace. When Chinese characters and numbers/ Latin characters are in the same text run, PPTX inserts extra spacing at the boundaries (e.g., "2025年7月" becomes "2025 年 7 月"). Minimize by keeping mixed strings as single text runs with a single fontFace — don't split into separate runs with different fonts.

  • CSS transforms (skew, rotate) need explicit conversion. CSS skewY(-3deg) doesn't have a direct PPTX equivalent. The closest approximation is the pptxgenjs rotate property on text/shape elements. Apply it explicitly — it won't transfer automatically.

  • Font substitution is silent. The pptx skill will swap fonts without warning if the specified font isn't available. Always verify font rendering in the QA step by comparing PPTX renders against HTML screenshots.

  • Don't skip QA. Seriously. The first PPTX compile is almost never correct. Every deck we've shipped required at least one fix-and-verify cycle. Budget time for it.

File Organization

  • tmp/ — Working drafts, style explorations, iteration artifacts (gitignored)
  • Final content Markdown — committed alongside the PPTX
  • Final HTML reference — committed alongside the PPTX for future modifications
  • Diagram source HTML + 2× PNG exports — committed in an assets directory
  • Final .pptx — the deliverable

Bundled Resources

Path What When to read
references/slide-design-styles.md Presentation styles (conventional + art movements), layout patterns, typography rules, color palettes, content-style matching, expert principles Before designing style options in Phase 2
../../examples/q2-report/ Complete worked example: content → 20-style exploration → 4 full decks (HTML + PPTX) To see the full workflow in action