html-to-pptx

html-to-pptx

When to trigger

The user expresses any of the following intents:

"Convert this HTML / web deck to PPT / pptx"
"I made HTML slides and need to give a colleague a ppt"
"It's inconvenient to present in a browser on site, I want a ppt file"
An HTML file path is available + mentions ppt / pptx / presentation / slides

Invocation

<skill_dir> is this skill's install path (usually ~/.claude/skills/html-to-pptx/, on Windows %USERPROFILE%\.claude\skills\html-to-pptx\). In the commands below, replace <skill_dir> with the actual path, or first cd <skill_dir> then directly python convert.py …。

python <skill_dir>/convert.py <input.html>

By default outputs to <input>.pptx
in the same directory as the input. Fonts are fully on-demand: fonts used by the HTML are fetched from Google Fonts during convert and embedded as subsets, cached to %LOCALAPPDATA%\html-to-pptx\fonts\ or ~/.cache/html-to-pptx/fonts/, and reused instantly next time for fonts with the same name
If the HTML contains CJK characters, Noto Sans SC + Noto Serif SC are automatically seeded (first time downloads about 40 MB / ~30s and instances static Regular/Bold, afterwards hits cache)
Families not available on GF fall back to the viewer's system fonts and print a warning

Option	Meaning
`--out <path>`	Custom output .pptx path
`--keep-screenshots`	Also keep a per-page HTML reference screenshot + `preflight.json`
`--no-embed-fonts`	Skip font embedding. Smaller file but falls back to system fonts on another machine
`--no-preflight`	Disable Stage 1 risk pre-scan
`--no-verify`	Disable Stage 5a structured self-check
`--no-visual-audit`	Disable Stage 5b visual audit material output. Do not disable in daily use
`--install-user-fonts`	Install the automatically resolved non-CJK fonts into the user font directory (so WPS can render correctly). Supported on Win/macOS/Linux.Must ask the user first, see the "Configuration confirmation" section below
`--only-slides N,N,N`	Incremental rerun. Comma-separated page numbers (1-based). measure only runs the specified pages + merges with the previous round's cached measurement; assemble/embed are still full; Stage 5a only renders the specified pages; Stage 5b only rebuilds the compare images for the specified pages—all other pages reuse the previous round's cache. For audit iteration rounds only, see the "Incremental rerun" section below
`--cleanup`	Do not convert. Delete the audit / measurement / preflight work artifacts next to input.pptx, keeping only the .pptx and audited.html.Use before final delivery, see the last step of the "Workflow" below

Working copy (the original HTML is untouched)

The first time python convert.py <input>.html finishes running, convert.py automatically cp's a copy of <input>.audited.html to the same directory as the source HTML. Mechanism:

All audit fixes modify audited.html, not the source HTML
Subsequent rounds of convert (including --only-slides) use <input>.audited.htmlas input, and the output is still <input>.pptx(automatically strips the .audited suffix)
audited.html already exists → reuse, do not overwrite (preserves the previous round's fixes)
If the agent mistakenly passes the source HTML as input → convert.py detects this internally and falls back to audited.html
cleanup does not delete audited.html (treated as a deliverable by-product, delivered together with .pptx )
To start from scratch → manually delete audited.html and rerun

Configuration (`.config.local.toml`）

Optional local preference file under the skill root, gitignored, one per user. Currently there are three types of preferences:

[fonts]
auto_install = "ask"   # "yes" 自动装、"no" 永不装、"ask" 由 agent 询问

[cleanup]
default = "clean"      # "clean" 工作流末步自动 cleanup、"keep" 保留 audit 产物

[audit]
mode = "ask"           # "triage" / "page" / "manual" / "ask" 由 agent 询问

File / key missing → use defaults (same as above)
Template:<skill_dir>/.config.local.toml.example
fonts.auto_install Read and applied forcibly by convert.py (=yes automatically adds --install-user-fonts, =no automatically ignores)
cleanup.default Read by the agent at the last step of the workflow to decide behavior
audit.mode Confirmed by the agent before the first convert; after Stage 5b, review is performed according to this value:
- "triage" → the main agent looks at audit_contact_*.png overview to triage, then dispatches a sub-agent to look at single images of shortlisted pages, saving tokens
- "page" → dispatch a sub-agent for every target page to look at the single-page slide_NN_compare.png, the strictest coverage
- "manual" → only generate review materials and hand them to the user for manual checking; fix after the user reports problems
- "ask" or missing → the agent collects the preference via AskUserQuestion and then rewrites this item (default)
First-time use: the agent collects fonts.auto_install and audit.mode via AskUserQuestion, thenwrites this file itself—the user does not need to create it manually

Configuration confirmation (completed before the first convert)

Two preferences must be confirmed before the first convert:fonts.auto_install and audit.mode. The process is the same; the only difference is in the trigger conditions and how the question is asked.

General process

Each preference is determined independently in the following order:

Read <skill_dir>/.config.local.toml, look at the corresponding field:
- Legal non- ask value → follow that value, do not ask again within the session
- ask or file / field missing → go to "trigger determination + ask"
If CLAUDE.md / global instructions specify an equivalent value, follow the specified value and also write the config (maintain a single source of truth)

After triggering, ask once via AskUserQuestion;both must be done：

Write <skill_dir>/.config.local.toml the corresponding field as the user's answer (do not write ask, otherwise it will be asked again in the next session)
Follow the answer in this session as well

When writing config: the filedoes not exist → Write the whole file to disk ([fonts] [cleanup] [audit] three-section template); the filealready exists → use Edit to do a single-line replace (change only this one field),do not Write to rewrite the whole file, otherwise it will swallow the user's other custom keys.

If both are triggered in the same session → merge them into the same AskUserQuestion and ask them all at once.

`fonts.auto_install` — Font installation

PowerPoint COM slide.Export() and WPS Office both do not read the bare TTF embedded in the pptx—audit rendering and WPS both fall back to system fonts. After installing to the user font directory, both follow system fonts. Directories (all user-level, can be deleted manually):

Windows: %LOCALAPPDATA%\Microsoft\Windows\Fonts\ + HKCU registry
macOS: ~/Library/Fonts/
Linux: ~/.local/share/fonts/ + fc-cache -f

Trigger determination: look at the HTML <head> in the <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / <style> inside font-family: font names that appear:

Trigger: any GF / self-hosted font (Bricolage Grotesque, DM Sans, Inter, Space Grotesk, Caveat, etc.)
Do not trigger: only use the system font whitelist (Arial, Times New Roman, Helvetica, Helvetica Neue, Courier, system-ui, -apple-system, BlinkMacSystemFont, SF Pro, Microsoft YaHei, SimSun, PingFang, Hiragino)

Per the reply: agree → add --install-user-fonts; reject → do not add.

`audit.mode` —— visual review mode

Three modes triage / page / manual(for meanings see the "Configuration" section above).Determined before the first convert of every session(not triggered by HTML content). AskUserQuestion uses a single-choice question, with the three modes as the options.

Workflow (mandatory)

convert.py finishing does not mean delivery is complete. The full process:

convert.py（首轮自动 cp <input>.audited.html，所有修复改这个副本）
  → Stage 5a 结构化自检（OOXML 扫描，给提示）
  → Stage 5b 视觉 audit 物料 — 需要 PowerPoint COM 或 LibreOffice 渲染器
  → 读 `audit.mode` 决定审查方式：triage / page / manual
  → 【agent audit】
        triage 模式：主 agent 读 contact sheet 分流 → sub-agent 看入围页单图 → 合并写 audit_findings.md
        page 模式：全量 sub-agent 看单页 → 合并写 audit_findings.md
        manual 模式：把 audit 物料交给用户，等待用户人工反馈
  → 按 finding 逐项做最小局部修改，目标是 audited.html（见下"修复纪律"）
  → 一批 finding 改完后 `convert.py <input>.audited.html --only-slides <被改页号>` + 只对 fresh 页重审（见下"增量重跑"）
  → 所有页 OK 或仅剩 LOW
  → 【若撞到 HTML 反模式 / 新 OOXML 边界】沉淀到 lessons-learned，见下方"沉淀 HTML 问题与 OOXML 边界"
  → 读 `<skill_dir>/.config.local.toml` 的 `cleanup.default`：
        "clean"（缺省）→ 直接 `python convert.py <out>.pptx --cleanup`，不问用户
                          清完目录剩：<input>.html（源，未动）+ <input>.audited.html（修复版）+ <out>.pptx
        "keep"        → 跳过 cleanup，audit 产物全部保留
  → 把 .pptx 路径交付给用户（audited.html 作为修复版 HTML 一同交付）

Vector-first principle (mandatory)

Content that can be expressed with PPT native text / shape / line should preferentially remain editable: ordinary background colors, ordinary four-sided borders, single-side lines, simple rectangles/ellipses, simple ::before / ::after wireframes should all use PPT shapes.

deco_snapshot only serves as a fallback for decorations that are hard to express in OOXML (for the hit conditions + full tier definitions + screenshot/vector layer coordination mechanism see references/supported-css.md). Do not uniformly screenshot ordinary lines, chart axes, and simple borders just to save effort—this sacrifices PPT editability and also makes subsequent local fixes harder.

Renderer requirements (Stage 5b prerequisites)

The Stage 5b visual audit needs to render the .pptx to PNG, depending on:

PowerPoint COM（Windows + Office + pywin32), or
LibreOffice(cross-platform, with pip install pdf2image）

If either is available, the audit can run. If you see [self-check] 跳过：找不到可用的 pptx 渲染器in the convert output, it means neither is installed—in this case the audit will notproduce compare images, and Stage 5b is skipped directly.

In this case the agent must ask the user(do not silently deliver an unaudited pptx):

"You have neither PowerPoint nor LibreOffice installed on your machine, so the visual audit cannot run, and the PPT may have visual bugs you cannot see. Three options:

Install LibreOffice (recommended, cross-platform, 2-3 minutes):winget install LibreOffice.LibreOffice（Windows）/ brew install --cask libreoffice（mac）/ apt install libreoffice(Linux), then pip install pdf2image, rerun convert

Skip the audit and deliver directly (accepting the risk that the PPT may have visual bugs)

Rerun on another machine that already has Office installed"

If the user chooses 1 → wait for them to finish installing and rerun; chooses 2 → add --no-visual-audit and run it once, then deliver after informing them of the risk; chooses 3 → send them the current directory + HTML.

Visual audit mode (config, prerequisite: 5b has run)

Before executing the visual review, read <skill_dir>/.config.local.toml of [audit].mode. Normally this should have been asked before the first convert via the "Configuration confirmation" above; if mode is still "ask"at this point (meaning the agent forgot to ask), immediately ask the user according to the "Configuration confirmation" section before continuing.

For the specific meaning of each mode see the "Configuration" section above; here only the applicable scenarios are listed:

mode	Applicable
`triage`	Default, saves tokens
`page`	Before final delivery, key clients, strictest user requirements
`manual`	User wants to look themselves

triage has a very clear division of labor:Round 1 contact pass = the main agent looks at thumbnails itself to triage (cheap, context already contains source HTML / Stage 5a / preflight)；Round 2 detail pass = dispatch shortlisted pages to a sub-agent to look at single-page compare images. You cannot judge HIGH/MID findings from thumbnails alone; to report a finding it must be confirmed via a Round 2 sub-agent single-page review.

Audit dispatch and compare image reading rules

page mode, all pages go through Claude Agent(...) sub-agent parallel dispatch.triage Only the Round 2 shortlist page in the mode goes through a sub-agent; the Round 1 contact sheet is Read by the main agent itself without dispatching a sub-agent.

The scenarios where the main agent actively reads the compare image are limited to the following five:

triage Round 1 reads audit_contact_*.png overview triage
Verification round for targeted fixes: this round has ≤ 2 fresh pages and the changes do not involve global CSS → the main agent directly reads the fresh page single images to re-check known findings + scan that page for new regressions,without dispatching a sub-agent(a sub-agent round takes 2-3 minutes, while direct reading takes only a few seconds). If there are more fresh pages or there are global changes, still go through a sub-agent
When a finding description is vague / conflicts with the source code and cannot be located, read the correspondingsingle page slide_NN_compare.png
Confirm by reading the single page before a sticky hit
When the user specifically gives feedback on a certain page, read the single page

Otherwise, do not Read the compare image page by page.

Split batches into smaller parallel ones optimized by wall-clock (a sub-agent serially reading large images is the main cause of latency; sending multiple small batches in parallel at full capacity is more than twice as fast as one large batch):

Number of slides	Strategy
≤ 2	1 batch
3-20	2 pages per batch, all sent in parallel
> 20	3 pages per batch (to control the total number of agents)

For the complete sub-agent invocation template + checklist + findings format, see <out>_audit/audit_prompt.md. Multiple Agent(..., run_in_background: true, subagent_type: "general-purpose") calls must be packed into the same message from the main agent to be parallel.

The sub-agent only returns findings text (in page mode it includes the ## page NN block for each target page; in triage detailed-review batches it includes the block for each page that was zoomed in and re-checked), and the main agent merges and writes them uniformly to audit_findings.md— concurrent writes will overwrite each other.

Each finding must name a stable short element name, and describe "the actual state of the HTML half-image; the difference in the PPT half-image". Only report visual issues that are newly added or enlarged in PPT relative to HTML; issues already present in the HTML half-image itself do not count as conversion findings.

Main agent preparations in parallel with the sub-agent (mandatory)

When initiating a page-mode or triage Round 2 detail sub-agent, the Agent call uses run_in_background: true, and inthe same message simultaneously send:

Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 5-9", prompt: ...)
Read(file_path: "<deck>/template.html")
Read(file_path: "<skill_dir>/references/lessons-learned.md")
Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
     output_mode: "content", -n: true)

Each sub-agent prompt must directly include this batch's slide_NN_compare.png absolute path, deck HTML path, andlessons-learned.md path (for the scope of application, see the "visual audit mode" section above); do not assume that the main agent's Read / Grep output will automatically be passed to the sub-agent.

Only send preparations that will be useful no matter what the findings are — do not predict findings and modify HTML in advance.

Fix discipline (target findings, do not chase root causes)

After receiving audit_findings.md ,finish fixing all findings of this round in one round, then rerun convert + audit all at once— not fix one and run once. One round = one batch of HTML edits + one convert + one audit.

After getting the findings:

Do notroutinely Read the compare image yourself (the findings already state the symptoms clearly); for the three exceptional cases of reading a single page for re-checking, see the "audit dispatch and compare image reading rules" section above
Do notread measure.py / assemble.py / any code inside the skill to find root causes
Directly open audited.html and fix item by item according to the findings

For each finding, make the minimal local HTML modification internally:

For each finding, change only the one place that "makes it disappear"; once done, move on to the next finding (keep editing the HTML, not rerunning convert)
Do nottrace the deep root cause of "why the font falls back / why the layout shifts"
Do notmake optimizations outside the finding list such as "while I'm at it, I'll also change .footer to absolute positioning"
Do notdo structural refactoring across findings ("uniformly declare font-family explicitly on all slides" ≠ the minimal fix for a single finding)
If the same finding appears intwo consecutive rounds(previous round + current round) → sticky hit, stop and tell the user,do notkeep expanding the scope of changes. Judgment key = (页号, 视觉元素短名)：
- Wording / severity / HIGH↔MID switching alldo not resetthe judgment. Example:(page 5, take 字号) described as "too small" in round 6 and as "severely insufficient" in round 7 → same sticky key, round 7 hits immediately
- Only when neither "page number + element" overlaps is it a new sticky key
- Alternate-round recovery: if it appears in round 6, disappears in round 7, and appears again in round 8 → not sticky (absence in round 7 is treated as the issue being fixed, and round 8 is a new regression)
- Hit = this rounddo not fixthat finding, list it as a skill boundary candidate and tell the user; other findings this round are still fixed
Implementation: after merging each round's audit_findings.md, before touching Edit, you must first Read the previous round's audit_findings.md(none for the first round) and do pairwise comparison — keys that appear inboththis round and the previous round are hits. Hit findings are listed separately for the user to judge and no longer enter this round's edit queue.

After this batch of findings is fixed, do a one-time python convert.py <input>.audited.html --only-slides <被改过的页号>。

Judgment standard: your diff line count ≤ number of findings × 3 lines. Exceeding this magnitude means you are "freelancing".

Incremental rerun (`--only-slides`）

used starting from audit round 2; the first round is full.

python convert.py <input>.audited.html --only-slides 2,7,12

Incremental coverage is measure / Stage 5a rendering / Stage 5b compare images, executed only for the listed pages + pages with missing cache; assemble / embed_fonts are still full.audit_index.json mark incremental_mode: true、fresh_indices、cached_indices, per page fresh: true/false。

The audit target pages for an incremental round take only fresh_indices。page mode directly dispatches these pages;triage mode first splits within these pages, then sends the shortlisted pages to the sub-agent.

Prerequisite: the previous round's <out>_audit/ directory still exists. Missing cache automatically falls back to full; changes in HTML page count are automatically detected and fall back to full measure.

Cannot use --only-slides cases(pages listed by visual overflow, cache false negatives):

Changes to global CSS (<style>, root selector,.slide general styles)
Adding / removing fonts (@import, font-family declaration changes)
Changes to deck-level tokens (background, theme color, spacing)
Any global variable change that affects the layout of other pages

For these categories, rerun full without a flag. If unsure → full rerun is always safe.

Accumulate HTML issues and OOXML boundaries (mandatory)

Your role isInvocation + usage accumulation, not fixing the skill. When you find a bug inside the skill,do not modify measure.py / assemble.py in place。

Only accumulate two categories:

1. HTML authoring issues (the user's HTML causes conversion distortion)

Category	Determination	What to do
One-off case (appears only in this deck, just change one or two lines of HTML)	Single-page special case	Directly edit the HTML source; don't accumulate, don't report
General HTML anti-pattern (anyone writing similar HTML will hit it)	Cross-deck	Edit HTML + accumulate to `references/lessons-learned.md` 's "HTML authoring avoidance" section

2. OOXML expressiveness boundaries (natively unsupported by PowerPoint / OOXML)

The vast majority of decorative CSS (backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / ::before ::after decorative usage—empty content + bg-image / box-shadow etc.) is already automatically captured by hasComplexDecoration in the "coverage strategy" and routed to deco_snapshot—HTML doesn't need changing。::before ::after string content（content: "↑" etc.) go through the text channel, see references/supported-css.md tier 1.

Real boundaries that still need an HTML workaround (natively inexpressible in the OOXML text layer):

Boundary	Alternative pathway
Color emoji (COLR/CPAL fonts)	Twemoji SVG `<img>`, embed via the img channel
`background-clip: text` text gradient	inline `<svg><text fill="url(#grad)">`, go through the SVG channel

Hit these two categories → change the HTML to use the alternative pathway + accumulate to references/lessons-learned.md 's "OOXML boundaries" section.

Hit a new unsupported CSS not in the table above → first check whether hasComplexDecoration is missing a trigger(just add one trigger condition), rather than changing the HTML. See references/supported-css.md 's "standard practice for adding new support".

How to handle something that looks like a bug inside the skill (don't fix, don't accumulate）

If you find that a symptom still occurs with the same CSS pattern on a different deck, and it's not within a known OOXML boundary → this is the skill's abstraction being inadequate.Do not modify the skill code in place. Do these two things:

For the current deck, use an HTML-side workaround to fix the finding, so the user gets a deliverable PPT
Clearly inform the user: "Found what looks like a general bug inside the skill: [symptom + triggering CSS pattern + current workaround]. Suggest the author record it as an issue so the skill handles this pattern more generally in measure/assemble"

Where to write accumulations: local copy + upstream template

references/lessons-learned.md isa per-user independent local working copy(gitignored). On the first run of convert.py , local_config.seed_lessons_learned() automatically copies one from the template lessons-learned.md.example(committed). The mechanism is the same as .config.local.toml .

The agent reads and writes the local lessons-learned.mdfor both investigation and accumulation—freely add / edit / organize, no git noise
The local copyis never overwritten by upstream——git pull pulls the .example template, without touching your working copy
To push an accumulation upstream:the author manually copies the entry back to lessons-learned.md.example commit again; selective curation, not push everything
Local business / client-specific writing → just write it in the local copy, it won't go upstream
lessons entries should only record reusable symptoms, trigger patterns, and avoidance rules; do not write specific local file names, template names, page numbers, client names, or source file names. Specific implementation locations, commands, and code details stay in the commit / issue / main skill documentation

Trigger: hit a general HTML anti-pattern / OOXML boundary → add it to the local lessons-learned.md lookup table. It is reread on every convert and takes effect immediately.

Override strategy (one sentence)

Inside the skill, all CSS is translated into four output tiers:Vector text → vector shapes → raster decoration (deco_snapshot) → direct media transfer. Simple bg-color / border / border-radius use the first two tiers (editable and searchable); box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / asymmetric rounded corners / clipping container + rotated child, etc. hit hasComplexDecoration and use the third tier (raster captures only the decorative pixels; text is always kept as vector drawn on top of the screenshot).

Full tier definitions / trigger conditions / guide for adding new support (vector first → screenshot fallback) → references/supported-css.md。

Pipeline

[1 输入识别/预扫] → [2 测量] → [3 组装] → [4 字体嵌入] → [5a 结构化自检] → [5b 视觉 audit]
   preflight.py    measure.py   assemble.py   embed_fonts.py  self_check.py    visual_audit.py

Actions for each stage / anti-assumption rules / exit assertions / new template checklist → references/methodology.md。

Stage 5b outputs <out>_audit/(compare image + contact sheet + audit_index.json + audit_prompt.md）。do not do pixel diff — numbers are insensitive to local bugs and give false confidence; visual judgment follows audit.mode for triage / page / manual. When there is no renderer, 5b is skipped; ask the user according to the "renderer requirements" section above.

Confirm before invocation

The input is a single-file HTML containing several slide elements (<section class="slide"> / <div class="slide"> / <deck-stage> child nodes etc. are all supported)
No need to configure a page-splitting mechanism for the user — the skill recognizes it automatically
The user calls it only after the HTML has already been written; just convert as required

Report

User feedback	Handling
Want to add pages / change text	Edit the source `<input>.html`(not audited.html, that is the audit-fixed version) → delete audited.html → rerun convert
Layout issues / text overflow / overflowing the frame	First check whether the HTML reference image also overflows; if the HTML is normal and the PPT is abnormal, troubleshoot according to `references/lessons-learned.md` Troubleshoot
Decoration displays as a square	Look at the compare image to determine whether it is geometry, screen capture, or renderer difference, and check `lessons-learned.md` 's OOXML boundary table
Wrong font (seen in PowerPoint)	Check the two items in `lessons-learned.md` "known regression checkpoint": GF font name normalization / weight slot assignment; if you hit them, work around them on the HTML side (change font name / adjust weight) + tell the author to file an issue
Wrong font (seen in WPS)	99% of the time WPS does not read bare TTF embedded fonts. Ask the user whether they agree to install it into the user font directory and then use `--install-user-fonts` Re-convert
Chinese displays as boxes □□□	Check whether the OOXML rPr's `<a:ea>` uses a CJK font
Centered text is positioned too low / outside the container	Check `lessons-learned.md` "known regression checkpoint"'s `flex + align-items:center` item; hit an HTML-side workaround (split container / change alignment) + tell the author to file an issue

Do not

Do not explain the full pipeline to the user (unless asked); only report the conversion result and warnings
Do not attribute the cause before looking at the audit compare image
Do not promise 1:1 visual fidelity — OOXML has limited expressiveness

Troubleshooting path

First determine the tier: 80% of findings are not bugs within a tier, but the wrong tier being chosen. Look at <out>_preflight.json or <out>_measurements.json to see which path this element took — text / shape / deco_snapshot / svg — and match against the symptom:

Symptom	Most likely cause
Took `deco_snapshot` but decoration is visually missing	Something was missed by the hide JS before the screenshot; or the deco area is smaller than expected
Took `text` but styles do not match (color / font size / line spacing)	measure did not capture all style fields / assemble missed translating fields
Took `shape` but rounded corners / border are wrong	border-radius value or `_round_kind` threshold
Visual effects (gradient / shadow / filter) completely lost	Should have taken deco_snapshot but did not — `hasComplexDecoration` was not triggered, add a line
Text disappears	Took the screenshot tier but did not emit the corresponding text record; or the hide JS hid things that should not be hidden

Then follow the usual process:

Look at the Stage 5a self-check report: which pages were warned about
Look at the Stage 5b audit results: by audit.mode get findings or manual feedback; only when user feedback / warning-corresponding pages need manual review, use Read to look at that page's compare image
Search references/lessons-learned.md for known symptoms (HTML anti-patterns / OOXML boundaries)
HTML is normal, PPT is abnormal and does not match a known boundary → check whether the skill abstraction is insufficient (follow the "how to handle what looks like a bug in the skill" process: fix the current deck with an HTML workaround + tell the user to file an issue)

Reference

Five-step anti-assumption pipeline + anti-assumption rules for each step + exit assertions + new template checklist → references/methodology.md(read when the author extends the skill; not necessary for agent invocation)
CSS coverage (detailed table of four tiers) + hasComplexDecoration complete trigger list + standard practice for adding new support → references/supported-css.md(read when the agent wants to understand which tier a CSS goes to; required reading for authors extending)
Historical pitfall fixes + HTML anti-patterns + OOXML boundaries → references/lessons-learned.md(required reading for agent troubleshooting). Local working copy (gitignored, automatically seeded from lessons-learned.md.example on first convert), freely add / modify / organize; to upstream an entry → the author manually copies it back to .example and commits