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.