nexu-io/open-design / plugins/community/humanize-ppt
humanize-ppt
VerifiedA presentation system for agent-made PPTs — born for the talk, not just the template. It turns raw material into an AST (audience-state-transfer) outline with per-page visual-enhancement decisions (image / SVG diagram / video), hands a production brief to a downstream renderer (HTML-PPT skills or native PPTX), then runs a capped 3-round presentation checkup (演讲体检) on the rendered deck. It never renders slides itself. Use before generating PPT/HTML slides from raw material, and after rendering when the user says things like "给这份 deck 做演讲体检" or "PPT 渲染质检". If all you want is one beautiful template page with no outline and no checkup, a rendering skill alone is enough.
SPEC.md
View on GitHub# Humanize PPT — Technical Specification
> Authoritative technical reference for the engine. `SKILL.md` is the
> agent-facing trigger doc; `README.md` / `README.en.md` are the public intro.
> This file specifies *what the engine does and guarantees*. Code-side source
> of truth is `scripts/humanize_ppt_v2.py` (stable entrypoint:
> `scripts/humanize_ppt.py`).
>
> Version: 1.1 · License: MIT · Author: LearnPrompt
## 1. Purpose & boundary
Humanize PPT is a **presentation system** for agent-made HTML presentations and native editable PPTX — built **for the talk**, not just the template. It is broadly compatible with downstream renderers that consume plain markdown + JSON; verified outputs now include both HTML decks and PPT Master's native DrawingML PowerPoint.
Three core capabilities frame everything:
1. **Outline director** — turns raw material (markdown / text / research doc) into an AST outline (audience-state-transfer; every page turn moves the audience forward) and a per-page production brief. Old `.ppt`/`.pptx` files are not read directly — extract their text first (`scripts/pptx_qa.py`), then pass the text as `--source`; a rendered `.pptx` is consumed via `--qa-from`, not `--source`.
2. **Visual-enhancement director** — decides, per page, whether the page needs an image (preferred: `baoyu-image-gen` via the local Codex CLI, no API key; alt: imagegen / imagen / nanobanana-ppt), a deterministic inline SVG diagram, or a video (Remotion), and emits machine-actionable asset slots (`asset_path` + `prompt_hint`).
3. **Presentation checkup + presenter hand-off** — auto-catches "look-only" pages after render (§7) and feeds presenter-mode speaker notes (§1 boundary below).
The downstream template skill renders the beautiful deck; Humanize orchestrates the talk. The hard boundary (the division of labor), unchanged since v0.6.4:
- Humanize never opens a downstream renderer's template.
- Humanize never injects sections into rendered HTML/PPTX.
- Humanize never post-processes rendered HTML/PPTX.
- When a downstream skill updates, Humanize needs zero changes.
Humanize decides **what** and **where**; the downstream skill produces the file. Humanize's own HTML remains zero-dependency working drafts, not decks. PPT Master style selection is delegated to its mandatory native Confirm UI rather than duplicated in Humanize.
## 2. AST — Audience-State-Transfer
- **Audience**: who listens, what they know, what they resist.
- **State**: audience state before/after the deck, plus the blocking tension.
- **Transfer**: the slide-by-slide path from initial to desired state.
Core sentence: *PPT is not an information container; it is an audience state-transfer artifact.* The role arc is `hook → context → tension → method → proof → takeaway` (`ROLE_ARC`).
## 3. CLI surface
```
python3 scripts/humanize_ppt.py --out <dir> [mode flags] [inputs] [renderer/style]
```
### Inputs (one required for brief/outline/gallery modes)
- `--source <path>` — markdown / text raw material. Old `.ppt`/`.pptx` are rejected (fail closed): extract text first via `scripts/pptx_qa.py`, then pass that text. A rendered `.pptx` goes through `--qa-from`, not `--source`.
- `--research-md <path>` — pre-existing research doc (e.g. hv-analysis output). Takes priority over `--source`; the brief writer does not re-parse raw material.
- `--title <str>` — deck title (required for non-QA modes).
### Modes (checked in this order in `main()`)
1. `--qa-from <rendered.html|native.pptx>` → **presentation checkup** (§7). Mutually exclusive with `--source`.
2. `--style-gallery` (v0.9) → **cover-style gate** (§6). Wins over `--preview-outline`.
3. `--preview-outline` → write `outline-preview.md` and stop (review checkpoint).
4. `--confirm-outline` → validate freshness, write `preview-confirmed.json`. Refuses if the outline is missing or the source mtime is newer. Mutually exclusive with `--preview-outline`.
5. (no mode flag) → **brief mode**: write the full output contract (§5) and the renderer's production prompt. Wipes and recreates `--out` first, but only when it is missing, empty, or already a Humanize PPT run (`run_manifest.json` / `style_gallery_plan.json` / `outline-preview.md` / `preview-confirmed.json` at its root) — otherwise refuses unless `--force` is passed.
### Renderer / style selection
- `--renderer {auto,guizang,beautiful-html-templates,html-ppt,frontend-slides,ppt-master}` (default `auto`). `ppt-master` is explicit unless `--ppt-master-template` forces it.
- `--guizang-style {A,B}` — A = flexible (5 themes), B = Swiss-locked (4 accents). A requires `--guizang-theme {ink-classic,indigo-porcelain,forest-ink,kraft-paper,dune}`; B requires `--guizang-accent {ikb,lemon-yellow,lemon-green,safety-orange}`.
- `--selected-template <slug>`, `--occasion`, `--mood`, `--preview-count` — beautiful-html-templates selection hints.
- `--gallery-count N` (v0.9) — style-gallery candidate count, minimum and default 4, capped at the candidates defined for the renderer.
- `--ppt-master-template <raw.pptx>` — forces PPT Master's native `template-fill-pptx` route.
- `--ppt-master-repo`, `--ppt-master-python` (verified Python ≥3.10), `--ppt-master-format`, `--ppt-master-project-name`, `--ppt-master-visual-style` — downstream runtime/location/project/confirmation recommendations.
- `--ppt-master-native-objects`, `--ppt-master-transition`, `--ppt-master-animation`, `--ppt-master-animation-trigger`, `--ppt-master-visual-review` — native export and explicit visual-review settings. On raw-template fill, only page transitions are written; existing native objects/animations are preserved and image replacement or new object animation is reported as a template-fill v1 boundary.
### Adapters & flags
`--presenter-adapter`, `--export-adapter`, `--presenter`, `--no-render`, `--skip-install-check`, `--max-qa-iterations N` (default 3), `--beautiful-repo`, `--no-beautiful-auto-clone`, `--force` (brief mode only — wipe a non-empty `--out` that is not already a Humanize PPT run).
## 4. Data flow
```
raw material
│ read_source → detect_language → build_slide_plan (per-role + decide_media)
▼
slide_plan.json ──(--style-gallery)──▶ ≥4 cover-only render commands + style_gallery.html picker ──pick──┐
│ │
│ (--preview-outline) ──▶ outline-preview.md ──(--confirm-outline)──▶ preview-confirmed.json │ reinjection_command
▼ ▼
brief mode: deck_brief / ast_outline / slide_plan / speaker_intent / asset_manifest / video_slots / style_brief
│ + <renderer>-production-prompt.md (per-page media block + media production guidance)
▼
downstream skill renders natively ──▶ rendered HTML or native PPTX
│
▼
--qa-from <rendered.html|native.pptx> ──▶ presentation checkup (≤3 rounds): qa_report.md / fix_prompt.md / qa_iteration.json
```
The brief is plain markdown + JSON. Verified recommendations: zh HTML → `guizang-ppt-skill`; en HTML → `frontend-slides` / `beautiful-html-templates`; native editable PowerPoint → `ppt-master`.
## 5. Output contract (brief mode)
Every brief run writes, into `--out`:
1. `deck_brief.md` — audience, goal, tension, success criteria.
2. `ast_outline.md` — AST map and narrative arc.
3. `slide_plan.json` — per-slide plan; schema `contracts/slide-plan.schema.json`.
4. `speaker_intent.md` — per-slide speaker action (downstream's source for native speaker notes).
5. `asset_manifest.md` — per-page material decisions.
6. `video_slots.json` — optional Remotion / HyperFrames insertion plan.
7. `style_brief.md` — visual principle for downstream production.
8. `renderer_registry.json` — renderer capability snapshot for this run.
9. `router_plan.json` — selected primary renderer + staged routes.
10. `commands/*.md` — bounded instructions per downstream specialist.
11. `<renderer>-production-prompt.md` — the brief the next agent consumes.
12. `run_manifest.json`, `outputs/qa/qa_report.md`, `outputs/qa/fix_list.md`.
PPT Master additionally writes `ppt-master-source.md` and disposable `outputs/ppt-master-handoff/` copies. The former freezes Humanize's semantic page contract; the latter lets PPT Master's main route obey its `import-sources --move` rule without moving the user's original file.
## 6. Style gallery (v0.9) — the cover-style gate
`--style-gallery` precedes the outline: it lets the human compare ≥4 covers side by side before committing to a style. Humanize emits the spec; the downstream skill renders the covers.
For the resolved renderer it takes the first `N` of `STYLE_GALLERY_CANDIDATES[renderer]` (guizang spans Style A themes + a Style B Swiss accent so the four covers are visually distinct) and writes:
- `commands/style-gallery/<id>.md` — a **cover-only** render command: render only S01 in that style → `outputs/style-gallery/<id>/cover.{html,png}`. Not a full deck.
- `style_gallery.html` — zero-dependency single-file picker stitching the covers via relative-path `<iframe>`s, each with its label, description, and re-injection command. A not-yet-rendered cover shows the frame backdrop plus an always-visible caption — no faked thumbnail.
- `style_gallery_plan.json` — per-candidate `id`, `label`, `description`, `cli`, `command_file`, `cover_html`, `cover_png`, `reinjection_command`.
After picking, the human runs the candidate's `reinjection_command`, which carries `--renderer` + style args into the normal outline → brief flow. Spec: `references/style-gallery-spec.md`.
PPT Master exception: `--renderer ppt-master --style-gallery` writes `style_gallery_plan.json` with `mode: downstream-confirm-ui` and `commands/style-gallery/ppt-master-confirm-ui.md`. It does not emit fake cover artifacts because PPT Master's mandatory Stage 1 already owns the visual-style catalog and native preview SVGs.
**WebGL static-screenshot trap**: Style A covers use a WebGL hero canvas whose PNG can capture blank (canvas paints after load). Each Style A cover command warns to treat `cover.html` as truth, delay screenshots ≥1.5s, and treat a `cover.png` under 20KB as a failed capture. See §7 and `references/qa-failure-modes.md`.
## 7. Presentation checkup (`--qa-from`)
Per-page review of rendered HTML or native PPTX against the outline — grades the outline, not beauty. Capped at `--max-qa-iterations` (default 3); unresolved findings at the cap flip `qa_status` to `needs-human`.
- `FAILURE_MODES` (in `humanize_ppt_v2.py`) is the code-side source of truth; the human-readable catalog is `references/qa-failure-modes.md` (+ English mirror `references/qa-failure-modes.en.md`), matched by id.
- Each round: `run_checks` → findings `[{id, severity, pages, evidence}]` → `qa_report.md` (human) + `fix_prompt.md` (downstream-actionable) + `qa_iteration.json` (round state).
- PPTX dispatch uses `scripts/pptx_qa.py::inspect_pptx`: OOXML package integrity, page count, placeholder residue, editable shapes, speaker notes, AST/notes drift, relationships, transitions, and requested native table/chart objects.
- Failure classes the static scan can't catch (text overflow, badge occlusion, the WebGL static-screenshot trap) are listed but not packaged as `FAILURE_MODES` rules — catalog discipline: only rules that exist in code.
## 8. Per-page media model
`build_slide_plan` calls `decide_media(role, title, message, visible_content, slide_id)`, which applies `ROLE_MEDIA_POLICY` per role and produces, for each of `image` / `diagram` / `video`:
- `needed` (bool), `kind` (e.g. `gpt-photo`, `screenshot`, `svg-html`, `remotion-clip`), and for `video` a `duration_s`.
- v0.6.7 machine-actionable fields: `asset_path` (where to write), `prompt_hint` (what to generate), plus `aspect_ratio` / `max_size_kb` for images.
A media slot **with** `asset_path` is an executable task; **without** one it is a label only. The three brief writers share `_format_per_page_media_block` (surfaces the slots) and `_media_production_guidance` (maps each `kind` to a concrete, hot-pluggable generator skill). Schema: `contracts/slide-plan.schema.json`.
## 9. Renderer registry
`registry/renderer_registry.json` snapshots renderer capability. `support_level` values, updated only on real results (宁空不摆拍):
- `guizang` → `full`
- `beautiful-html-templates` → `full` (brief exit + real Neo-Grid checkup + 5 English-specific modes)
- `frontend-slides` → `full` (brief exit + real frontend-slides checkup + the same 5 English-specific modes)
- `ppt-master` → `full` (main + raw template-fill real routes, 11 PPTX-specific modes, real 10-page main export and 5-page template-fill export/checkup on 2026-07-10)
## 10. Versioning & tests
- `VERSION` in `humanize_ppt_v2.py`. Version history under `docs/versions/`.
- Tests in `tests/` (pytest); run `python3 -m pytest -q`. v0.9 adds `tests/test_v090_style_gallery.py`.
- The Luban discipline for this project: 验料 (confirm baseline green) → 访行 (read the existing flow) → 过尺 (run pytest) → 慢刨 (implement) → 回炉 (registry / SKILL.md / version / marketplace). Release actions (push / tag / marketplace bump) are gated on human review.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |