Deep Ppt

deepPPT Skill — Research-style Academic Slides

Skill directory: the folder containing this SKILL.md. Do not assume a fixed /home/... or /Users/... install path; resolve bundled scripts and references relative to this file.

What This Skill Is

deepPPT is a merged + specialized skill built on top of:

• pptx skill — technical implementation (create / edit / pack / QA)
• academic-pptx skill — content structure, action titles, evidence-first slides
• deepPPT visual template — the concrete Chinese-academic aesthetic taken from the reference decks in references/example_pptx/ (Tianjin University style):
• Cover slide segmented top rule: dark navy on the left fading to white on the right
• Blue title bar accents + segmented title divider fading from blue/navy to white
• Chevron (▸) section subheaders
• Blue-bordered text callout boxes
• Red-bordered "key takeaway" box at the bottom on substantive content slides — never on outline / agenda / table-of-contents slides
• Centered figures with blue subcaptions
• Formal figure captions in the form 图N · 主题

Use this skill whenever the user wants a PPT that looks like the PPT Ref deck rather than a generic Western conference slide.

Quick Reference

| Task | Where | |------|-------| | Visual style / color / typography | [styleguide.md](styleguide.md) | | Per-slide-type patterns (cover, background, results, take-home) | [slidepatterns.md](slidepatterns.md) | | Creating from scratch with pptxgenjs | [pptxgenjs.md](pptxgenjs.md) | | Editing an existing .pptx template | [editing.md](editing.md) | | Content rules | See "Content Rules" below |

Platform Support

deepPPT is intended to run from Codex, Claude Code, OpenClaw, and other local-agent clients on macOS or Windows, but it should be used for final PPT generation only in a full-power environment. Do not run final deck generation from the OS-bundled Python if it is older than 3.12 or lacks the required QA packages.

Create a project-local virtual environment in the skill directory, install the full toolchain, then run the environment check with that venv Python:

cd 
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/check_env.py

Rules:

• If Full-power status is not PASS, install the missing software first.

Do not treat degraded mode as acceptable for final PPT generation.

• Final visual sign-off also requires a vision-capable reviewer in the current

agent loop, or an explicit human visual review of the rendered PNG/contact sheet. Text-only models may generate decks and run deterministic QA, but they must not claim final visual quality control by themselves.

• Codex may generate one intro concept image when the Codex image generation

tool is available. Claude Code, OpenClaw, and unknown runtimes must skip that generated image path.

• Command examples use the venv's python after activation. On Windows, run

commands from ` and use py -3.12 -m venv .venv plus .venv\Scripts\python`.

Runtime / Model Capability Tiers

deepPPT has two QA layers:

1. Deterministic QA: extract_pptx_text.py, qa_layout.py, zip/package

validation, and render-backend checks. This works with text-only coding models because the model only needs command output.

1. Rendered visual QA: inspecting slide PNGs/contact sheets for readability,

crop errors, text overflow, unwanted visual weight, low contrast, and taste. This requires either a model/platform that can read images or a human review.

Use this decision rule:

| Runtime/model capability | Allowed role | Final sign-off | |---|---|---| | Text-only coding model (for example a model whose docs list text input only) | Build scripts, edit PPTX XML, run deterministic QA, produce preview files | No; hand off preview PNGs/contact sheet to a vision reviewer or human | | Vision-capable model exposed through the current agent platform | Build, run deterministic QA, inspect rendered slide PNGs, iterate layout | Yes, after render preview plus qa_layout.py pass | | Text model + separate vision model/tool available | Text model builds; vision model/tool reviews the rendered PNGs | Yes, if the vision review is actually run and findings are fixed |

Do not make the model choice about "best coder" only. For deepPPT final delivery, the blocking capability is rendered-slide vision access. Strong text-only models such as coding-specialized LLMs can be useful builders, but they need a vision/human QA partner before delivery.

Content Rules

• Use action titles: a content slide title should state the point, not merely name the chart.
• Each result slide needs one proof object: a source figure, chart, table, or clearly sourced calculation.
• Keep one main claim per slide. If two figures both need to be read, split the slide; a secondary figure may stay only when it is a small contextual inset.
• Keep the red bottom box to one conclusion sentence; do not turn it into a second paragraph. Do not add it to outline / agenda / table-of-contents slides.
• The rendered preview at 150 dpi must make figure labels, group names, and key table values readable. If not, enlarge the evidence object, crop nonessential whitespace, or split the content.
• Visible figure captions should be audience-facing only: 图N · 主题 / 表N · 主题 / 概念图 · 主题. Do not write build or provenance traces such as AI-generated, Source figure extracted, from original deck, model names, or tool names on the slide.
• If source data, citations, or figure provenance need disclosure, put them in speaker-facing notes or the final handoff, not as visible slide text.
• Ghost-deck test: reading only slide titles plus red bottom boxes should recover the argument; outline / agenda / table-of-contents slides are navigation and do not need red bottom boxes.

Workflow

1. Ingest source (paper PDF / existing .pptx). If editing existing slides, first run /.venv/bin/python /scripts/extract_pptx_text.py input.pptx to dump deterministic PPTX text, then /.venv/bin/python /scripts/render_preview.py input.pptx --out preview to see layouts. On Windows, use \.venv\Scripts\python with the same script paths. MarkItDown is required in the full-power environment for richer extraction when the deck/source format needs it; the stdlib extractor remains the lowest-level sanity check.
2. Plan deck outline — list each slide as [slide type] | [action title]. Confirm with user if > 8 slides or content is ambiguous. Treat 汇报大纲 / 目录 / Outline / Agenda slides as navigation slides: reuse the title-bar and row/table style, but never apply the bottom red key-finding workflow to them.
3. Write build script — use pptxgenjs (LAYOUTWIDE, 13.333 × 7.5"). Import helpers from [styleguide.md](style_guide.md) at the top. Do not improvise new colors or new title bar shapes — deviations kill the "同一个人做的" feel.

• If the current operator is Codex and a Codex image generation tool is available (image2 / built-in image generation), one early intro/background slide may include a generated concept schematic. Generate it as a supporting orientation image only, save it under the deck's local assets/ directory, then place it with the intro concept pattern in [slidepatterns.md](slidepatterns.md). Do not label the visible slide with AI-generated or tool provenance.
• If the current operator is not Codex, or the runtime/tool availability is unknown, do not generate or embed an intro-page concept image. Use text, native shapes, tables, or real source figures instead.

1. Build: run /.venv/bin/python /scripts/run_node_with_deps.py build_pptx_deep.js in the output directory.
2. QA loop:

• /.venv/bin/python /scripts/extract_pptx_text.py output.pptx — dependency-light content check
• /.venv/bin/python /scripts/qa_layout.py output.pptx — blocking structural check for duplicate rules, outline-slide red boxes, provenance labels, and chevron/title collisions / too-tight spacing
• /.venv/bin/python /scripts/render_preview.py output.pptx --out preview — visual render with platform PowerPoint first, then LibreOffice fallback
• Open slides visually and hunt for: overlap, low contrast, missing red-box, off-grid titles, cut-off text.
• Fix, rerun qa_layout.py, and re-render; repeat until both automated QA and the full visual pass are clean.
• If render_preview.py cannot run, the environment is not full-power; install the missing backend before final delivery.

Non-negotiable Visual Rules

Follow these exactly — they are what make reference decks look like one person made all of them:

1. All horizontal template rules are segmented gradients: the cover slide uses a thin segmented rule around y = 1.30" that fades from dark navy (1F3864) on the left to white on the right; content slides use the same segmented-gradient rule style under the title around y = 1.15". Do not replace any slide's horizontal rule with a single light-blue line.
2. Title bar is always the same shape: two small blue rectangles on the left + black title text + segmented blue/navy-to-white rule below. Never swap in a full-width filled blue header bar.
3. Every content slide has at least one blue ▸ chevron header introducing the subtopic.
4. Every substantive content slide ends with a red-bordered key-finding box at the bottom unless it is a cover, outline / agenda / table-of-contents slide, figure-only slide, references, or thank-you slide. Red text, bold, centered. This is the "bottom line" the audience must walk away with.
5. Figures are centered in the content area without extra outer frames. Do not draw a blue rectangle around an image just to contain it. Use an optional blue bold caption above and a formal muted caption below when needed.
6. No duplicate template rules: before adding a segmented rule to an edited/copied slide, remove any inherited flat horizontal hairline from the same slide. If the extra line comes from a layout/master and cannot be removed from slide XML, hide it with a white no-line mask or switch to a blank layout, then render-check the slide. Thank-you/closing slides get one template rule only.
7. Figure titles must clear section headers: if a figure has a separate small title above it, place that title at least 0.20" below the full-width chevron header's bottom edge; lower or shrink the figure instead of letting title text overlap.
8. Body text has blue-bordered callout boxes for quoted/key paragraphs — not filled, just 1 pt blue line.
9. Font: Arial (Western) / Microsoft YaHei or PingFang SC (Chinese) — one face per deck. Bold for everything titled; regular for body.
10. Colors — use ONLY the palette defined in style_guide.md; generated charts may use the CHART_* data colors only for data marks. No random teals, greens, or decorative gradients.
11. Codex-only intro concept image gate — generated concept art is allowed only for Codex users with an available image generation tool, and only on an intro/background slide. It must not be used as evidence, must not contain invented data, labels, logos, watermarks, or fake chart axes, and must not show AI-generated, model, or tool provenance as visible slide text.
12. Cover slide has no bottom keyword strip — do not add decorative blue bars, slogan strips, or keyword ribbons at the bottom of a cover unless the user explicitly asks for them. Keep the cover vertically balanced with title, author, affiliation, advisor, and date only.

Scripts (inherited from pptx)

| Script | Purpose | |--------|---------| | scripts/check_env.py | Cross-platform environment check for generation and visual QA backends | | scripts/extract_pptx_text.py | Standard-library PPTX text extraction for content QA | | scripts/qa_layout.py | Blocking PPTX XML layout QA for duplicate rules, outline-slide red boxes, forbidden captions, and chevron/title clearance | | scripts/render_preview.py | Cross-platform PPTX preview renderer with backend fallbacks | | scripts/run_node_with_deps.py | Run generated Node build scripts with global npm packages on NODE_PATH | | scripts/thumbnail.py | Optional grid of slide thumbnails for template analysis | | scripts/office/unpack.py | Extract pptx into editable XML tree | | scripts/office/pack.py | Repack XML tree into .pptx with validation | | scripts/office/soffice.py | Optional headless LibreOffice wrapper for PDF export | | scripts/add_slide.py | Clone a slide or instantiate a layout | | scripts/clean.py | Drop orphaned slides / media / rels |

QA Checklist (deepPPT-specific)

□ Cover slide: red-bold occasion label + big navy title + blue bold author + black affiliation/date
□ Cover slide keeps the segmented navy-to-white top template rule
□ Content slides use segmented gradient title dividers, not single-color hairlines
□ No slide has duplicate horizontal template rules
□ Cover slide has no bottom keyword strip or decorative footer ribbon unless explicitly requested
□ Every content slide has the standard title bar (two blue squares + black title + thin rule)
□ Every content slide has ≥ 1 blue ▸ chevron subheader
□ Every substantive content slide ends with a red-bordered key-finding box (≈ 0.55–0.75" high, full content width)
□ Outline / agenda / table-of-contents slides do not have a red bottom key-finding box
□ Figures centered horizontally, with no extra blue outer frame around the image
□ Figure/subfigure titles sit with visible air below chevron headers and do not overlap source-image internal titles
□ Figure labels are formal captions only (`图N · 主题`, `表N · 主题`, or `概念图 · 主题`)
□ No visible `AI-generated`, `Source figure extracted`, model name, tool name, or original-deck provenance text
□ Only palette colors are used (navy / blue / red / black / muted-gray / off-white panel)
□ Generated charts use only `CHART_*` colors for data marks, never for headings or decoration
□ Single font face throughout
□ Body text ≥ 16 pt
□ At 150 dpi preview, figure labels and key table values are readable without zooming into individual PNG pixels
□ If an intro concept image appears: current runtime is Codex, asset exists under the deck's assets folder, and the image is clearly a non-evidence concept schematic
□ If current runtime is not Codex or unknown: no generated intro-page image is present
□ Ghost-deck test passes: reading action titles alone tells the argument
□ No decorative icons, no clip art, no unintentional gradients

Dependencies

Full-power requirements:

• Python 3.12+ in a project-local .venv (Python 3.12 is the recommended stable target)
• Node.js with pptxgenjs resolvable by the same node used to run build scripts
• Microsoft PowerPoint desktop for the current platform:
• macOS: /Applications/Microsoft PowerPoint.app
• Windows: PowerPoint desktop with PowerShell COM automation available
• Python packages: pypdfium2, Pillow, markitdown[pptx], defusedxml, lxml
• Resilience renderers: LibreOffice (soffice) and Poppler (pdftoppm)

macOS install commands:

cd 
brew install node python@3.12 poppler
brew install --cask libreoffice
npm install -g pptxgenjs
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/check_env.py

Windows install expectations:

• Install Microsoft PowerPoint desktop, Node.js, Python 3.12, LibreOffice, and Poppler.
• Run npm install -g pptxgenjs.
• Create .venv with py -3.12 -m venv .venv, then install requirements.txt.
• Run .venv\Scripts\python scripts\check_env.py; final generation is allowed only when it reports Full-power status: PASS.

PowerPoint remains the fidelity renderer on macOS/Windows. LibreOffice and Poppler are required because they make QA and fallback rendering resilient, but they must not replace the platform-native PowerPoint visual check for final quality.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jiadizhunine
• Source: jiadizhunine/deepPPT
• License: MIT

Install and usage instructions live in the source repository linked above.