# Deck Craft

> 从源材料出发、端到端打造投影就绪的高质量 .pptx 演示成片，覆盖设计系统、python-pptx 构建、逐页专家精修、去 AI 味、演讲逐字稿与备注。当用户要做 PPT / 幻灯片 / 演示文稿 / 课程或工作汇报 / slide deck / presentation，尤其是内容密集、面向投影、要求「高质量 / 精修 / 专业 / 不要 AI 味」的报告型 deck，或要把调研材料整合成一套有叙事的幻灯片、需要中文排版与思源字体、需要演讲稿时，都应使用本技能；即便用户只说「帮我做个 PPT」或「把这些材料做成汇报」也要触发。本技能面向中文及中英混排、输出 .pptx 的投影 deck。判定分界：如果用户要的是内容密集、需要逐页精修、需要去 AI 味的报告型 .pptx deck，用本技能；如果只是单页简单图、纯数据表格导出、机械生成单个 .pptx，或已有 deck 仅做一两处微调，则不适用（轻量单文件 .pptx 读写改用公开的 pptx 技能）。

- Skill: `o0000-code/deck-craft` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add o0000-code/deck-craft`
- Raw SKILL.md: https://api.skillmd.com/api/skills/o0000-code/deck-craft/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: Apache-2.0. LICENSE.txt has complete terms
- Author: o0000-code (https://skillmd.com/u/o0000-code)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/o0000-code/deck-craft

---


# deck-craft

Build projection-ready, content-dense, high-quality presentation decks from source
material, through a disciplined pipeline: understand → unify the information spine →
ready the environment & fonts → research-design round → build → render QA →
per-page expert polish → de-AI-ify → speaker script → speaker notes. The output is
a `.pptx` (plus a PDF for sharing, and an optional notes version) that reads
cleanly when projected and tells one coherent story.

This skill encodes a complete, reusable design system in `scripts/deck_kit.py` and
the methodology in `references/`. Read this body for what to do and when; go to the
referenced files for the detail.

## 1. When to use / not use

This skill is oriented to **Chinese / mixed CJK-latin projection decks** (the divider
chapter labels and the like are localizable to English; see §3 P-build and the
`CHAPTER_LABEL` token in `deck_kit.py`).

The dividing line is the **kind of work**, not just the trigger words:

- **Light, single-`.pptx` read/write or mechanical generation** (parse a deck, pull
  its text, emit one slide from data, drop comments in, split/merge files): use the
  `pptx` skill. It is the right tool when no narrative design or per-page polish is
  needed.
- **Research-driven narrative + per-page expert polish + projection typography +
  de-AI-ified report-grade deck** (turn a pile of research / interview / report
  material into one coherent, projection-facing story, then iterate it to high
  quality): use **this** skill. That is the report-grade case the whole pipeline
  below exists for.
- If you have a more general-purpose slide pipeline available, reach for this skill
  specifically when the deck must be content-dense, projection-readable (16 pt body
  floor), and free of AI tone.

**Not for:** a single one-off diagram, a plain data-table export, or a one- or
two-spot tweak to an existing deck.

## 2. Core principles (three invariants)

1. **Projection floor: body >= 16 pt; quiet luxury.** A 13.333 in canvas on a 2–4 m
   screen viewed from 3–8 m has a far smaller visual angle than a web page at arm's
   length, so any text carrying real information stays >= 16 pt. The look is white /
   near-white foundation (~90%) + a neutral grey scale + ONE desaturated accent used
   only as garnish (<5% area), with no full-page color blocks.
2. **findings-first.** Introduce the object objectively (what it is, what's there,
   what's good) BEFORE diagnosing it. "If you don't introduce it, how can you talk
   about its flaws?" The arc is introduce → diagnose → improve → close.
3. **Iterate only on the real render, never on an imagined one.** python-pptx is
   invisible; CJK fallback, overflow, and line-breaks only show up rendered. Render
   after every layout-affecting change and look before judging.

## 3. The nine-step pipeline (P0–P9)

**Match the ceremony to the task size.** A 5–10 page small deck trims P3 and P6:
build directly with `deck_kit.py` and do one self-review round; the "lead self-builds
and self-verifies" lines below are about who owns quality, not a ban on a quick path.
Only a content-dense large report walks the full parallel-expert flow. Default for a
real report is the whole pipeline; full detail and the WHY of each step is in
`references/pipeline.md`.

- **P0 · Understand the domain** (lead agent, not outsourced): read the course /
  brand / business material, align on audience and taste, output a short alignment
  note. Building context yourself is what lets you judge and synthesize.
- **P1 · Absorb sources + lock the information spine** (lead): convert all sources
  to md, read each, find framework conflicts, and lock ONE backbone (others map
  under it). A deck's quality is first its information architecture. See
  `references/content_and_narrative.md`.
- **P2 · Environment & fonts ready** (lead): verify python-pptx / Pillow / render
  chain; install premium fonts and **render-test Regular + Bold before a full
  build**. Run `scripts/install_fonts.sh`; see `references/build_and_qa.md` §7. No
  network? `install_fonts.sh` now skips the download and you fall back to an
  installed system CJK font (macOS PingFang SC, or an already-installed 思源 / Source
  Han); point `deck_kit.py`'s SANS/SERIF at it and render-verify.
- **P3 · Research-design round**: write a per-round planning doc, then launch three
  parallel experts in ONE message (design-system [load practical-ui if present] ‖
  content & narrative [findings-first] ‖ image audit [verify every image]); each persists an
  md; then the **lead writes the synthesis doc itself** (per-page asset assignment +
  build increments). See `references/{design_system,content_and_narrative,image_audit}.md`.
- **P4 · Build**: prefer the lead self-building the script with `scripts/deck_kit.py`
  (see `scripts/example_build.py` for the pattern, including `cards()` / `compare()`
  and the multi-chapter dispatch loop). The lead holding the script is what drives
  the per-page iteration. If you outsource, force the sub-agent to persist the script
  to a file and save incrementally (a build sub-agent once dropped its socket having
  saved nothing).
- **P5 · Render QA**: `soffice → pdf → pdftoppm → PIL overview`; look at high-risk
  layouts first. Run `scripts/render_qa.py deck.pptx`. No LibreOffice? Open the
  `.pptx` in PowerPoint or Keynote and export a PDF (or per-slide thumbnails), then
  eyeball those instead. See `references/build_and_qa.md`.
- **P6 · Per-page expert polish**: split pages into bands, launch several review
  experts in parallel (each loads practical-ui if present, uses the design system as
  yardstick, returns pixel-level findings); the **lead verifies findings itself**, rejecting
  false positives and taking only real ones, then fixes, re-renders, and runs a
  regression round. The gate to clear: **at least one parallel review round plus one
  regression round, with no open P0/P1.**
- **P7 · De-AI-ify**: load humanizer-zh (op7418's public MIT skill; if it isn't
  installed, install it on demand with `npx skills add op7418/Humanizer-zh` and load
  it — if you truly can't, run `references/humanize.md`'s deck-specific checklist by
  hand); edit layout-coupled deck text yourself (re-render to watch length); change
  HOW it's said not WHAT (prove technical content unchanged with grep); **second
  self-check** so you don't swap one AI pattern for another. See `references/humanize.md`.
- **P8 · Speaker script**: if the user hand-edited the deck, extract real per-page
  text from the LATEST file (the build script is now stale); write a spoken,
  `---`-paginated, emphasis-marked script; deliver the MD for confirmation BEFORE
  inserting.
- **P9 · Insert speaker notes**: run `scripts/insert_notes.py` (drops headings +
  〔...〕 cues, splits the body on blank lines into paragraphs, converts `**bold**`,
  asserts segment==slide count, writes a NEW file).

## 4. Sub-agent orchestration

> This section assumes a Claude Code-style harness (parallel sub-agents; the Skill
> tool). On any other agent runtime, read these as their semantic equivalents:
> "sub-agents" → background or delegated sub-tasks, and "load a Skill via the Skill
> tool" → load the corresponding capability. The method is unchanged; only the
> mechanism's name is.

- **Research round (P3):** three parallel experts in one message, all blocking
  (design ‖ content ‖ image audit). Write the per-round planning doc first so all
  three align on background, locked decisions, source paths, and output contract.
- **Review rounds (P6):** several parallel review experts, each prompted to (1) if
  `practical-ui` is installed, load it via the Skill tool as the usability yardstick
  — it is a copyrighted-book adaptation this skill does not bundle, so when it is
  absent fall back to this skill's own quiet-luxury / contrast / hierarchy principles
  (`references/design_system.md`); (2) read the design system as the yardstick, (3)
  return page/location/severity findings.
- **The lead must verify review findings itself.** Fix observed problems, not
  reported ones; reject unfounded reports (a "slide N font too small (P0)" that the
  render disproves) and take only real, actionable items.
- **Heavy build:** prefer the lead self-holding context and self-building. If
  outsourced, require "persist the script to a file before continuing, save
  incrementally".

Parallel = N Agent calls in ONE message, all blocking. One call per message =
serial. Independent → parallel; dependent → serial. Full table in
`references/pipeline.md`.

## 5. Quality gates (checklists)

Full version with the "why" in `references/norms_and_lessons.md` §E. Quick form:

**Before build:** [ ] lead read all sources itself · [ ] frameworks unified into
one backbone · [ ] narrative is findings-first (setup chapter before diagnosis) ·
[ ] image-audit list done (figure ≠ file) · [ ] type scale locked (body >= 16 pt) ·
[ ] copy written plain (no AI tells) · [ ] premium fonts installed + render-verified
(or system-font fallback chosen if no network) · [ ] content tied to course/audience
theory · [ ] names only on the cover · [ ] heavy build self-built (or sub-agent
persists early).

**After build:** [ ] every layout change re-rendered and eyeballed (no LibreOffice
→ PowerPoint/Keynote PDF or thumbnails) · [ ] per-band parallel review experts (each
loads practical-ui if present, else the built-in design system) · [ ] lead verified high-impact findings, rejected false
positives · [ ] render chain macOS/zsh-safe · [ ] at least one review round plus one
regression round, no open P0/P1.

**Before delivery:** [ ] de-toning second self-check (no pattern swapped for
another) · [ ] versioning `_vN.M`, archive old, new file for user-edited files · [ ]
known boundaries/risks listed with a fallback (font fallback → PDF; no LibreOffice →
PowerPoint/Keynote) · [ ] citations verified if any.

## 6. Norms quick-reference (the full list)

These 13 norms are the deck-making domain knowledge; the full requirement / why /
how for each is in `references/norms_and_lessons.md` §A.

1. **findings-first:** introduce before you critique.
2. **De-name:** member names only on the cover role cards; never per-page kickers.
3. **Chapter divider per chapter,** with a "chapter X of N" progress indicator.
4. **Body >= 16 pt:** projection floor; dense tables 14 pt is the only exception.
5. **Premium fonts:** Noto Serif SC (titles) + Noto Sans SC (body) + Inter
   (numbers); install and render-test both weights before a full build.
6. **Verify every image by eye:** figure number ≠ file number; contact sheet +
   full-res check; only verified images with corrected captions.
7. **Simplified cover:** white, restrained, accent as garnish.
8. **Minimal ending:** one centered serif line on white; references moved out.
9. **Design yardstick — practical-ui if present, else built-in:** if `practical-ui`
   is installed, load it as the usability yardstick; it is a copyrighted-book
   adaptation this skill does not bundle, so when absent, use this skill's own
   quiet-luxury color, accent <5%, no full-page color blocks (`design_system.md`).
10. **Per-page expert polish, not one-and-done:** render → parallel review → lead
    verifies → fix → re-render → regression; iterate to no open P0/P1.
11. **De-AI-ify with humanizer-zh:** op7418's public MIT skill — install it on demand
    if absent (`npx skills add op7418/Humanizer-zh`), else run `humanize.md`'s
    deck-specific checklist by hand; change how not what; prove technical content
    unchanged with grep; second self-check.
12. **Speaker script:** extract from the real .pptx; `---` per page; spoken,
    emphasis-marked; confirm the MD before inserting.
13. **Insert notes, spoken body only:** drop headings & 〔...〕; convert bold;
    segment==slide assertion; write a new file.

This skill carries its own working discipline, self-contained (it needs no external
rule files): understand before you act, audit before you execute, back up before
irreversible rework, re-render on every visual change and judge only the real render,
keep the palette desaturated (quiet luxury), make every iteration state its benefit,
resolve multi-source conflicts by authority level, use four-zone directories with
`_vN.M` versioning, and verify any citation before delivery. How each plays out in
deck work is in `references/norms_and_lessons.md` §B.

## 7. Quick start

A typical run: read the user's source material yourself, lock the spine, set the
accent token, then drive the build from data.

**Work in your own project, not the skill folder.** Copy `deck_kit.py` (and the
`example_build.py` skeleton) into your project's working area and write your build
script there. Leave the files under the skill directory untouched so the skill stays
clean for the next deck.

1. `bash scripts/install_fonts.sh` (once), then render the example and confirm
   Regular vs Bold are distinct: `python3 scripts/example_build.py && python3
   scripts/render_qa.py scripts/example_deck.pptx`.
2. Copy `deck_kit.py` into your project's working area, drop the
   `example_build.py` skeleton beside it, set `dk.set_accent("#XXXXXX")` and
   `dk.FOOTER_TEXT`, and replace the EXAMPLE content with your outline (see
   `assets/content_outline.schema.md`).
3. Build → `python3 render_qa.py your_deck.pptx` → read `/tmp/qa/overview.png`
   → fix → re-render. Iterate per §3 P6.
4. Speaker script → `python3 insert_notes.py --md script.md --src deck.pptx
   --out deck_with_notes.pptx`.

**Scripts** (`scripts/`): `deck_kit.py` (the reusable design-system library, the
heart), `example_build.py` (a worked example with cards/compare + a multi-chapter
loop), `insert_notes.py`, `render_qa.py`, `contact_sheet.py`, `install_fonts.sh`.

**References** (`references/`): `pipeline.md`, `design_system.md`, `build_and_qa.md`,
`image_audit.md`, `content_and_narrative.md`, `humanize.md`, `norms_and_lessons.md`.

**Versioning:** non-destructive. New versions go as `_vN.M` to the deliverables zone,
superseded versions to the archive zone, and a user-edited file is always copied to
a new file, never overwritten.