jaw-pptx

# PPTX Skill Use this skill for PowerPoint `.pptx` creation, editing, review, and QA. Triggers: `"PowerPoint"`, `"PPTX"`, `"presentation"`, `"slides"`, `"deck"`. **OfficeCLI routing and consent rule:** - First check whether `officecli` is available with a probe that works in the agent's actual shell: `command -v officecli` on POSIX, `Get-Command officecli -ErrorAction SilentlyContinue` in PowerShell. **`command -v` is not a PowerShell builtin or cmdlet** — on Windows it prints nothing, sets no exit code, and raises no error, so it is indistinguishable from "not installed" and the agent asks to install a tool that is already there (#298). `officecli --version` is the portable fallback: a non-zero exit or no output means missing. - If installed, recommend OfficeCLI first for high-fidelity PPTX mutations, validation, query, batch/resident flows, CJK/rhwp-aware work, and Office-compatible output. - If missing, do not auto-install. Present choices before proceeding: 1. Install forked OfficeCLI from `https://github.com/lidge-jun/OfficeCLI` via `bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh"`. 2. Continue with lightweight fallback tools for the current task, with limitations stated. 3. Stop or cancel. - Before taking a lightweight fallback path, ask the user again and state what fidelity/features may be lost. - If the user chooses lightweight mode, save that preference to memory for future Office work. - Use upstream/vanilla `iOfficeAI/OfficeCLI` only when the user explicitly asks for upstream behavior. OfficeCLI is the recommended advanced backend for slide add/set/remove, validate, and query workflows. Lightweight fallback: **pptxgenjs** for large programmatic generation (50+ data-driven slides) and **Python scripts** (`scripts/*.py`) for unpack/repair/thumbnail/cleanup when OfficeCLI is unavailable or the user chooses lightweight mode. See §3. Do NOT use this skill for Keynote, Google Slides API automation, or image generation. **OfficeCLI discovery rule:** use the installed CLI as the source of truth. Run `officecli --help` for workflows and `officecli help pptx ... --json` before inventing element/property names. **Same-file execution rule:** run OfficeCLI commands against the same `.pptx` sequentially. Do not run `officecli view`, `officecli validate`, `officecli query`, or `officecli get` in parallel against one package. If a file lock occurs, stop and report the exact command and path before making a copy or retrying. --- ## 1. Quick Reference | Task | Action | |------|--------| | **Format like existing deck** | `cp source.pptx target.pptx && officecli open target.pptx` — **inherit theme/layouts/masters. See §2.** | | Read / analyze content | `view` and `get` commands (see Core Workflows) | | Edit existing presentation | Read [editing.md](./editing.md) | | Create from scratch | Read [creating.md](./creating.md) | | Pitch deck (Seed / Series) | Read [officecli-pitch-deck/SKILL.md](./officecli-pitch-deck/SKILL.md) | | Morph transition animations | Read [morph-ppt/SKILL.md](./morph-ppt/SKILL.md) | | 3D morph effects with models | Read [morph-ppt-3d/SKILL.md](./morph-ppt-3d/SKILL.md) | | JS programmatic fallback | Read [pptxgenjs.md](./pptxgenjs.md) | | Color palette / typography | Read `references/design-system.md` — 20 palettes, 8 font pairings | | Thumbnail grid / visual QA | `python3 scripts/thumbnail.py deck.pptx grid.png` | | Unpack / repair | `python3 scripts/pptx_cli.py {open\|save\|validate\|repair}` | **Execution model:** Run commands one at a time. Check exit code before proceeding. Non-zero = stop and fix. --- ## 2. Reference-Based Editing (Edit > Create from Scratch) When the user says "format like X.pptx", "match existing deck style", "based on template", or provides a source file — **start from the source. Don't rebuild from scratch.** ### Workflow 1. **Copy the source**: `cp source.pptx target.pptx` — inherits theme, slide masters, layouts, fonts, colors 2. **Open** with `officecli open target.pptx` — daemon returns immediately (do NOT run as `run_in_background`) 3. **Remove slide content** but keep `/slideMaster`, `/slideLayout`, `/theme` 4. **Add new slides** using existing layouts (`--prop layout=Title+Content`) — they auto-inherit theme ### Why This Matters Slide master and theme definitions (fonts, colors, placeholder geometry) are document-specific. Recreating them from scratch: - Loses consistent branding across slides - Breaks existing placeholder positions - Takes 5-10× longer than modifying the copy ### Template Sources (priority order) 1. **User-provided source file** — first-class template 2. **`tests/fixtures/*.pptx`** — pre-built examples shipped with this skill 3. **`officecli-pitch-deck/` templates** — if pitch/investor context 4. **`morph-ppt/reference/styles/*`** — 51 curated style definitions (`bw--brutalist`, `dark--aurora-softedge`, `light--minimal-product`, etc.) 5. **`officecli create`** blank — only when nothing else applies ### Example — Inherit Existing Brand ```bash # CORRECT: inherit theme and layouts cp CompanyBrand.pptx Q4Report.pptx officecli open Q4Report.pptx officecli remove Q4Report.pptx "/slide[1]" # remove sample slides officecli add Q4Report.pptx / --type slide --prop layout=Title officecli add Q4Report.pptx '/slide[1]' --type textbox --prop text="Q4 Report" --prop placeholder=title officecli close Q4Report.pptx # WRONG: recreate theme (loses brand) officecli create Q4Report.pptx # ... add all fonts, colors, masters from scratch ... ``` --- ## 3. Reference Materials & Script Map officecli covers most PPTX tasks. For design, QA, and repair, use these references + scripts. ### References (`references/`) | File | Read when | Contains | |------|-----------|----------| | `references/design-system.md` | **Before picking colors/fonts** — palette + typography decision | 20 palettes (business/nature/energy/tech/warm), 8 font pairings, 4 Korean fonts | ### Deep-Dive Files (inside subskills) These are specific reference files nested inside subskill folders. Load only the one you need. §4 lists the top-level subskill SKILL.md entry points. | Path | Read when | Contains | |------|-----------|----------| | `morph-ppt/reference/decision-rules.md` | Planning framework for content-heavy decks | Pyramid Principle, SCQA, page types | | `morph-ppt/reference/pptx-design.md` | Canvas spec, ghost position math | Canvas, fonts, spacing tokens (x=36cm ghost) | | `morph-ppt/reference/styles/INDEX.md` | Picking a distinct visual style | 51 style definitions with spec + example | | `morph-ppt/reference/quality-gates.md` | Phase 4–5 QA gates for morph decks | QA checklist | | `morph-ppt/reference/officecli-pptx-min.md` | Morph-specific officecli commands | Minimal command reference | | `pptxgenjs.md` | Programmatic generation (50+ data-driven slides) | PptxGenJS API reference | | `recipes.md` | 3 copy-paste repair patterns | Section divider z-order, KPI overflow, timeline spacing | ### Scripts (`scripts/`) — Python OOXML Toolkit | Script | Run when | Command | |--------|----------|---------| | `scripts/pptx_cli.py` | Unified Python CLI — unpack, save, validate, repair, thumbnail, search, TOC, add-slide, clean, export-pdf | `python3 scripts/pptx_cli.py {open\|save\|validate\|repair\|text\|search\|toc\|thumbnail\|export-pdf\|add-slide\|clean}` | | `scripts/thumbnail.py` | Slide thumbnail grid or individual PNGs (visual QA) | `python3 scripts/thumbnail.py IN.pptx grid.png` or `IN.pptx out_dir/ --individual` | | `scripts/clean.py` | Find/remove orphaned media/files from unpacked PPTX | `python3 scripts/clean.py work/ [--delete]` | | `scripts/add_slide.py` | Add or duplicate slides on unpacked dir (legacy OOXML) | `python3 scripts/add_slide.py work/ --blank` or `--duplicate 3 --position 1` | | `scripts/run_tests.py` | Run skill regression tests (fixtures + expected outputs) | `python3 scripts/run_tests.py` | ### Editing Escalation Ladder When officecli can't do the job, escalate in this order: | Level | When | Tool | |-------|------|------| | **L1** officecli high-level | Typical slide/shape add/set/remove | `officecli add/set/remove/query/view` | | **L2** officecli `raw-set` | XML injection — custom animations, chart XML, theme tweaks | `officecli raw-set FILE PATH --xpath X --action A --xml ...` | | **L3** Python script | Thumbnail generation, orphan cleanup, unified CLI ops | `python3 scripts/*.py` | | **L4** Unpack → edit XML → repack | Morph transitions beyond officecli, custom `p:transition` XML, macro handling | `scripts/pptx_cli.py open` → edit `work/ppt/slides/*.xml` → `save` | | **L5** pptxgenjs | 50+ slides from datasets, composable factories, heavy loop logic | `npm install pptxgenjs` + JS pipeline | **Escalation signals:** - officecli shows **"silently ignored"** or unsupported prop → **L2** - Need **morph/custom transitions** beyond high-level → **L4** - **Bulk generation** from data (50+ slides) → **L5** (pptxgenjs) - **Unpacked workflow** for cleanup/reorg → **L3** (`pptx_cli.py clean`) - **Design pick** (color, font, style) → Read `references/design-system.md` + `morph-ppt/reference/styles/INDEX.md` FIRST --- ## 4. Subskill References Load ONLY the one subskill matching your task. Do not load all of them. | Task | Subskill | Path | |------|----------|------| | General PPTX | This file + recipes | [creating.md](./creating.md) / [editing.md](./editing.md) | | Pitch deck | officecli-pitch-deck | [./officecli-pitch-deck/SKILL.md](./officecli-pitch-deck/SKILL.md) | | Morph animations | morph-ppt | [./morph-ppt/SKILL.md](./morph-ppt/SKILL.md) | | 3D morph | morph-ppt-3d | [./morph-ppt-3d/SKILL.md](./morph-ppt-3d/SKILL.md) | | JS fallback | pptxgenjs | [./pptxgenjs.md](./pptxgenjs.md) | --- ## 5. Slide Design Guidance Design is a deliverable, not optional polish. A slide deck is not a document: if the largest element plus one glance does not communicate the slide's point, the hierarchy has failed. > **The 3-second test.** Every slide must pass it — a viewer grasps the one point in 3 seconds. Wrong chart type, bullet walls, and weak hierarchy all fail it. Canonical owners (read for depth; this skill carries the slide-adapted essentials inline): > - Design-direction / intent discovery, hierarchy levers → `jaw-dev-uiux-design` skill. > - Anti-slop philosophy + render verification → `jaw-dev-frontend` skill. ### 5.1 Slide Design Read Before styling, state: deck type, audience, the decision the audience must make, existing brand/template, and the dominant visual reference. If a `DESIGN.md` or template exists, it overrides. ### 5.2 Before starting - **Pick a bold, content-informed color palette.** It should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices. - **One color dominates** (60-70% visual weight), with 1-2 supporting tones and one sharp accent. - **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel. Reference files: > - Full palettes + Text/Muted columns + personality map: `references/design-system.md`. > - Slide-adapted hierarchy levers + per-slide checklist: `references/visual-hierarchy.md`. > - Copy-paste visual-effect recipes (gradient/shadow/glow/etc.): `references/visual-effects.md`. > - Distinct design styles: `morph-ppt/reference/styles/INDEX.md` (51 curated styles). ### 5.3 Intent Discovery for Decks When deck direction is vague ("멋지게 만들어줘", "깔끔하게"), ask up to 4 binary/ternary questions before building. If the user names a reference product, skip to mapping via `references/design-system.md`. (Adapted from `jaw-dev-uiux-design` §1; "viewport" step dropped — slides are fixed 16:9.) 1. **Mood** — "청중에게 남길 느낌: `executive/trustworthy` · `premium/editorial` · `energetic/product-launch` · `technical/precise` · `training/clear` 중?" 2. **Density** — "한 장당 정보 밀도: `keynote sparse`(한 메시지) · `business normal`(제목+시각+짧은 근거) · `review dense`(차트/표 중심) 중?" 3. **Shape language** — "도형 언어: `sharp grid`(정밀/컨설팅) · `soft cards`(친근/제품) · `editorial bleed`(이미지/큰 타이포) · `diagrammatic`(프로세스/시스템) 중?" 4. **Reference / template** — "따라야 할 기준: `existing template/brand deck` · `product ref (Linear/Apple/Stripe)` · `industry convention` · `no reference — propose one` 중?" Answers feed the dials below with reasoned values instead of defaults. ### 5.4 Deck Dials Before creating, decide these three parameters. Present to user if ambiguous. | Dial | Range | Default | Meaning | |------|-------|---------|---------| | DESIGN_VARIANCE | 1-10 | 4 | 1 = symmetric grid, 10 = asymmetric art-directed | | VISUAL_DENSITY | 1-10 | 5 | 1 = gallery whitespace, 10 = dashboard dense | | MOTION_INTENSITY | 1-10 | 3 | 1 = static cuts, 10 = cinematic morph | Presets by deck type: | Deck type | VARIANCE | DENSITY | MOTION |