# PPTX Visible Academic Deck Zh

> Use when Codex needs to create, revise, or QA a Chinese academic PowerPoint deck from a paper, report, thesis, proposal, PDF, or PPT template, especially when the user wants Microsoft PowerPoint opened visibly and edited page by page. Applies to .pptx template reuse, PDF figure extraction, PowerPoint COM automation, speaker notes, formula/LaTeX assets, scenario cards, reducing whitespace, visual QA exports, and preventing missing notes, tiny table text, leftover template placeholders, or invisible generation that stays on one slide.

- Skill: `hoangxuanthu54755-lang/pptx-visible-academic-deck-zh` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hoangxuanthu54755-lang/pptx-visible-academic-deck-zh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangxuanthu54755-lang/pptx-visible-academic-deck-zh/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: hoangxuanthu54755-lang (https://skillmd.com/u/hoangxuanthu54755-lang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hoangxuanthu54755-lang/pptx-visible-academic-deck-zh

---


# PPTX Visible Academic Deck ZH

## Core Goal

Create an academic PPT that feels designed, readable, and presentation-ready. Use the user's template style, keep PowerPoint visibly open, switch to each slide as it is generated, write complete speaker notes, and validate the rendered slides.

This skill is specialized for local Microsoft PowerPoint COM workflows. Combine it with the general `pptx` skill when lower-level PPTX parsing, thumbnailing, XML editing, or generic PPT conversion is needed.

When the source is a PDF, combine this skill with the general `pdf` skill for text extraction, page rendering, table extraction, OCR, and image extraction.

## Default Workflow

0. Run environment discovery before assuming paths.
   Use `scripts/discover_powerpoint.py` to locate `POWERPNT.EXE`, check likely Office install records, and optionally verify COM. Different users may install Office/PowerPoint in different folders; do not hardcode one user's `C:\Program Files\Microsoft Office\root\Office16\POWERPNT.EXE` path unless discovery confirms it.

1. Read the paper/report and any provided template.
   Extract the argument, empirical design, key results, mechanisms, policy implications, and any figures/tables. Do not make a chapter-by-chapter slide dump.

2. Select the visual baseline.
   If the user specifies a `.pptx` or `.potx` template, use that file as the visual authority. If no template is specified, do not reuse a private local template from a prior user; create a clean deck with the fallback academic style in `Template Selection`.

3. Analyze the selected template or fallback style before creating slides.
   For a user-provided template, export template thumbnails, inspect fonts, color palette, logos, header/footer lines, title page style, content card style, notes conventions, and image assets. For the fallback style, define the palette, title band, card grammar, formula treatment, and notes convention before generating slides.

4. Open the user-provided template visibly as a reference when one exists, but create a clean new presentation.
   Do not overwrite the template. `Presentation.Save` can fail if a copied template is treated as read-only; prefer `Presentations.Add()` and `SaveAs()` a new `.pptx`. If no template is provided, create the new presentation directly and apply the fallback academic style.

5. Build a narrative deck plan.
   Compress the source into a talk sequence such as: problem/contribution -> framework/roadmap -> data and identification -> main result -> mechanisms -> counterfactual or policy -> conclusion.

6. Generate slides through visible PowerPoint COM.
   `app.Visible = True` is not enough. Before editing each slide, activate the presentation window and call `ActiveWindow.View.GotoSlide(slide.SlideIndex)` with a short delay so the user can see the process.

7. Write speaker notes for every slide.
   Notes are a default requirement for academic decks and a hard gate when the template has notes. Write, read back, fall back if needed, and block delivery if any slide has empty notes unless the user explicitly asks for no notes.

8. Export all slides to PNG and inspect.
   Create a contact sheet sorted by slide number, zoom into critical slides, fix issues, and re-export after fixes.

## Environment Discovery Preflight

Before visible deck generation on a new computer, locate PowerPoint and verify automation:

```bash
python scripts/discover_powerpoint.py --out powerpoint_discovery.json
python scripts/discover_powerpoint.py --check-com --out powerpoint_discovery_com.json
```

Use the JSON fields as follows:

- `preferred_executable`: path to use when a script needs to launch PowerPoint explicitly.
- `found_executables`: fallback candidate paths.
- `uninstall_records`: version and install-location clues for diagnostics.
- `com.available`: whether direct COM automation worked when `--check-com` was used.

If no executable is found but COM works, direct `PowerPoint.Application` automation may still be enough. If neither executable nor COM is available, stop and tell the user PowerPoint is not discoverable on this machine instead of silently producing a non-visible substitute.

Visible editing is mandatory when requested:

- Start with `PowerPoint.Application`.
- Set `Visible = True`.
- Activate the target presentation window.
- Call `ActiveWindow.View.GotoSlide(slide.SlideIndex)` before editing each slide, with a short delay.
- Do not leave the visible UI on one slide while editing later slides in the background.

## Narrative Compression

PPT is not a paper summary. It is a presentation route.

Use this structure for empirical economics or policy research by default:

| Slide role | Preferred visual grammar |
|---|---|
| Opening/title | Template title style, concise topic signal |
| Research question | Left-side problem path + right-side question cards |
| Contribution | Strict 2x2 equal-width/equal-height matrix |
| Technical route | Four-stage or five-stage large process cards |
| Data/institution | Figure + numeric callout cards |
| Identification | Timeline, shock card, or intuition cards |
| Main result | Large result card + formula/result card |
| Mechanism | Decomposition formula + channel cards |
| Heterogeneity | Segmented cards or small multiples, not dense tables |
| Policy/counterfactual | Scenario cards + directional arrows + conclusion band |
| Conclusion | Three takeaways or policy toolbox |

Change the sequence when the source demands it, but keep each slide's component grammar tied to its logical role.

## Template Selection

Follow this priority order:

1. User-specified template path.
   Use it as the visual source of truth: fonts, colors, title bars, header/footer rules, logos, page-number style, spacing rhythm, and note conventions. Create a new `.pptx`; never overwrite the template.
2. Project-local template if the user explicitly says to use the current project's default.
   Discover it from project notes or a clearly named template folder, then still inspect it before use.
3. Built-in fallback style when no template is specified.
   Use a restrained Chinese academic forum style: white or very light background, strong but thin title band, blue/teal primary accent, one warm secondary accent, structured cards, small section labels, consistent page number/footer line, and no decorative marketing graphics.

The fallback style is not a bundled `.pptx` file. It is a reproducible layout system generated through PowerPoint shapes, text boxes, formula PNG assets, and consistent geometry. This makes the skill portable to other users without copying a private template.

## Template Reuse

Preserve the template's identity without copying stale content:

- Reuse logos, title bars, header lines, page numbers, color accents, and spacing rhythm.
- Remove old template titles, placeholders, old project names, and stale notes.
- Keep template-like visual assets if they support the new deck.
- Use a stable output path and create an accepted-baseline copy when the user approves a version.

For Chinese academic forum templates, a quiet white content page with a strong title band, thin blue header line, structured cards, and restrained accent colors often works better than a flashy generic business deck.

## Visible PowerPoint COM

Use direct COM when the user wants to watch local editing:

```python
import win32com.client as win32
app = win32.Dispatch("PowerPoint.Application")
app.Visible = True
```

For each slide:

```python
slide = pres.Slides.Add(index, layout)
app.ActiveWindow.View.GotoSlide(slide.SlideIndex)
time.sleep(0.18)
```

If PowerPoint has multiple windows, activate the target presentation window before `GotoSlide`. Do not leave the UI stuck on slide 1 while the script edits later slides invisibly.

When inserting images:

- Validate optional image paths with `Path(path).is_file()`.
- Do not use `Path("").exists()`, because empty strings resolve to the current directory on Windows.
- If an optional figure is missing, skip it or use a layout fallback instead of letting `Shapes.AddPicture` crash.

## PDF Source And Figure Assets

When the user provides a PDF paper rather than `.tex`, do not assume the original figure files exist. Build slide-ready assets from the PDF itself.

Use this decision order:

1. Extract text and locate figure/table candidates.
   Use PDF text extraction to find captions such as `Figure 1`, `Fig. 1`, `Table 2`, `图1`, `表2`, and nearby section names. Record page numbers and captions before choosing slide visuals.
2. Render candidate pages to high-resolution PNG for visual inspection.
   This is the default reliable path because academic PDF figures are often vector drawings or mixed text/vector objects, not standalone raster images.
3. Crop the figure/table region from the rendered page.
   Use fractional crop boxes after inspecting the rendered page. Keep captions only when they help interpretation; otherwise replace the caption with a clean slide title or note.
4. Extract embedded images only as a secondary path.
   `pdfimages` or PDF image extraction may return panel fragments, logos, texture pieces, or raw images without axes/labels when the published figure is vector. Use extracted images only if they preserve the full figure semantics.
5. Insert the cleaned PNG into PowerPoint and perform visual QA.
   Check resolution, aspect ratio, legibility of axis labels, absence of page headers/footers, and whether the figure should be paired with number cards or explanatory callouts.

Bundled helper script:

```bash
# Render pages 5-7 to PNG for inspection.
python scripts/extract_pdf_assets.py paper.pdf --out-dir outputs/pdf_assets --pages 5-7 --render-pages --dpi 300

# Crop one figure from page 6 using fractional coordinates.
python scripts/extract_pdf_assets.py paper.pdf --out-dir outputs/pdf_assets --crop-page 6 --crop 0.10,0.18,0.92,0.62 --name fig2_main --dpi 300

# Try embedded image extraction when the PDF stores full raster figures.
python scripts/extract_pdf_assets.py paper.pdf --out-dir outputs/pdf_assets --pages 5-7 --extract-images --min-width 500 --min-height 350
```

Dependencies: prefer `PyMuPDF` (`fitz`) and `Pillow`; use Poppler tools such as `pdftoppm` or `pdfimages` as fallbacks when available.

Crop rules for PPT:

- Use 250-300 dpi for ordinary slide figures; use 400 dpi for small labels or dense tables.
- Avoid screenshots taken from a low-zoom PDF viewer; render from the PDF file directly.
- Preserve the full plot area, axes, legends, and panel labels.
- Remove surrounding PDF whitespace, page numbers, journal headers, and unrelated captions.
- If a table is too dense after cropping, convert it into cards instead of inserting the full table image.
- Save extracted assets under a stable output folder and insert by absolute path after `Path(path).is_file()` succeeds.

## Slide Design Rules

Use fixed ratios and formula-derived positions rather than eyeballing.

Recommended academic content sizes:

- Main content slide title: about 26-30 pt.
- Section label or eyebrow: about 13-15 pt.
- Body card text: about 16-18 pt.
- Dense auxiliary text or captions: about 10-12 pt.
- Key numbers: about 30-36 pt.

Avoid body text below 12 pt except footers, captions, or small labels. If a table requires 10-11 pt body text and still looks sparse, replace the table with cards.

Use semantic colors:

- Blue: institution, identification, baseline design.
- Teal: data, mechanism, allocation.
- Gold: structure, cost, model objects.
- Green: policy, welfare, toolbox.
- Red: risk, constraints, environmental burden.

Do not make every slide the same horizontal bar layout. Mix:

- Left path + right question cards.
- 2x2 contribution matrix.
- Four-stage route cards.
- Chart plus number cards.
- Formula/result cards.
- Three-channel mechanism cards.
- Scenario cards.
- Conclusion band.

## Alignment And Whitespace

Alignment beats filling every inch.

- Use 2x2 matrices for contribution-style slides; derive all `x/y/w/h` values from constants.
- Use equal-width scenario cards for 4-6 scenarios.
- Use fixed gutters such as 0.18-0.30 in and apply them consistently.
- Use card headers, separators, and content zones to make short text look intentional.
- Do not solve large blank areas only by increasing font size.

Diagnose whitespace:

- Sparse table cells -> convert to cards.
- Ugly English/math variable text -> render formulas or localize labels.
- Bottom text touches border -> reduce value font or increase explanation-zone height.
- Similar cards misalign -> unify coordinate formula, title height, separator position, and card width.

## Formula And English Variable Rules

Classify every English/math token before rendering:

0. Treat variable names from empirical files as presentation objects, not raw code.
   Regression variables, table headers, dataset fields, and source-code names such as `lnrd`, `wage_salary_share`, `capex_labor_ratio`, `TFP_OP`, or `CoalShare` must not be pasted into PPT as raw snake_case/plain English by default. For audience-facing slides, either localize them into Chinese metric labels or render them as LaTeX formula assets, for example `$\ln RD$`, `$\mathrm{WageShare}_{it}$`, `$\mathrm{TFP}^{OP}$`, `$\mathrm{Capex}/\mathrm{Labor}$`. Keep raw variable names only in notes, appendix data dictionaries, or small technical footnotes when traceability is needed.

1. Keep method/model/stage names in English when they are scholarly labels:
   `Bunching`, `SMM`, `ITT`, `Stage 1/2`, `Baseline`, `CF-2`.

2. Render mathematical objects as formula assets when they contain subscripts, hats, Greek letters, `ln`, arrows, bundles, decomposition, or structural equations:
   `p_i S + FC`, `\widehat{\delta}`, `\mathrm{TFP}_{OP}`, `\ln \mathrm{EI}`, `TFP ↑ / CoalShare ↑`, `EI, CI ↑ / R&D ↓`.

3. Localize explanatory metrics in ordinary cards:
   `TFP 上升` -> `生产率上升`; `Coal` -> `煤炭`; `CO2` -> `碳排`; `PowerShare` -> `电力占比` when the card is not a formula card.

Reliable formula PNG pattern:

```text
standalone LaTeX + amsmath + xelatex
pdftoppm -png -r 300 formula.pdf formula
insert resulting PNG into PowerPoint
```

Formula/result cards must have three checked zones:

- Formula zone.
- Value/result zone.
- Explanation zone.

Do not check only whether the formula is clear. Confirm the explanatory text is not clipped, too small, or touching the card border.

## Speaker Notes Hard Gate

When a template has notes, every generated slide must have speaker notes.

Default notes length: about 100-180 Chinese characters per slide, adjusted for talk speed and slide density.

Write notes through COM, then read them back:

```python
slide.NotesPage.Shapes.Placeholders(2).TextFrame.TextRange.Text = notes
```

If the standard placeholder write fails or reads back empty:

1. Search notes placeholders by name and placeholder type.
2. Try Chinese placeholder names if present.
3. Add a fallback text box on the notes page.
4. Re-read notes.
5. If any slide still has empty notes, do not save or deliver.

Always report notes completeness, not just slide count.

## QA Gate

Minimum validation before delivery:

1. `python -m py_compile` for generation scripts.
2. PowerPoint opens visibly and visits slides during generation.
3. SaveAs produces a new `.pptx`.
4. Export every slide to PNG.
5. Sort slide PNGs by numeric slide number, not string order.
6. Create a contact sheet.
7. Zoom into critical pages: contribution matrix, route page, result page, mechanism page, scenario/policy page.
8. Extract text and search for old template placeholders or old project content.
9. Check notes length for every slide.
10. Check for body text below 12 pt on key slides.
11. Fix at least one QA pass when issues are found, then re-export affected slides.

Look specifically for:

- Misaligned rows in a 2x2 matrix.
- Bottom explanations clipped by card borders.
- Tables with tiny text and empty cells.
- Formula text rendered as ugly plain text.
- Missing notes after SaveAs.
- Old template title or placeholder residue.
- Content not fitting its shape.
- Too much unbalanced whitespace.

## Deliverables

For a complete deck task, provide:

- New `.pptx`, never overwriting the template.
- Stable accepted-baseline copy if the user approves the result.
- Formula asset folder when formula PNGs are generated.
- PNG export folder and contact sheet.
- Notes completeness report.
- Short QA summary listing visual checks and any known residual risk.

## Common Failure Repairs

- **Slide looks like a paper pasted into PPT**: reduce text, move explanation into notes, use cards.
- **Page has too much blank table space**: convert table to scenario/result/mechanism cards.
- **English variables look rough**: formulaize math, localize explanatory metric labels.
- **PowerPoint is visible but user cannot see progress**: call `GotoSlide` for every slide.
- **Notes vanished**: read back notes after writing and use fallback notes text box.
- **Contribution page rows do not align**: rebuild as 2x2 formula-derived matrix.
- **Template residue remains**: extract text and grep placeholders/old titles before delivery.

## Sharing This Skill

When publishing or sharing, copy the entire `pptx-visible-academic-deck-zh` folder, not only `SKILL.md`. The folder may contain `agents/openai.yaml` and `scripts/discover_powerpoint.py`; both are part of the reusable skill package.