What this skill does
Treats a deck as a build, not a document:
| Artifact | Role |
|---|---|
template.pptx | the toolchain — its slides are the archetype catalog. Always required. |
deck.mdx | the source — the only file anyone edits |
assets/*.svg | generated art, also source — content only, no design |
deck.pptx | the build artifact — regenerated in full every time |
deck.pdf + page previews | what a person actually looks at — the only place layout is |
Each output slide is a clone of a template slide with its content swapped, so the template's design survives byte for byte. Nothing is laid out from scratch.
Engine: scripts/deck.py (invoke with an absolute path).
Recolor (any pptx; for a built deck, recolor template.pptx and rebuild): scripts/ppt_keycolor_changer.py,
procedure and presets in references/recolor.md — discover, map by lightness, confirm, replace, verify.
Standing Mandates
- Never build without a reference template. There is no built-in deck design and no fallback. If the user has not given you a
.pptx, stop and ask for one — do not assemble slides some other way, do not offer a generic deck, do not fabricate a template. The engine refuses too, but the ask belongs to you, before any work. - The source file is
deck.mdx, neverdeck.md. It is compiled, not read. The engine rejects any other extension. - Catalog before writing. Never author
deck.mdxfrom a guess about the template. Runcatalogand write against the slot ids it prints. - Never hand-edit the output pptx. It is regenerated on the next build. Corrections go into
deck.mdx. - Run
checkbeforebuild, and show the user the warnings. Overflow warnings are what stands between crowded text and a slide nobody can read. - Visibility decides, not tidiness.
| transparentis right when the image's content stays legible against the slide;checksays when it would not, and a panel behind the image is the better answer there. Don't reach for transparency because it sounds cleaner. - Never crop away content without saying so.
checkreports the percentage; repeat it to the user and offer| fit. A picture losing half of itself is the same defect as a table row falling off the slide. - Never hand-author a picture slot's art as a binary. Write the SVG so the deck stays reproducible from text. A PNG someone pasted in cannot be regenerated, re-colored, or reviewed in a diff.
- A deck is read by people, so look at it. When a renderer is available, finish with
render, notbuild— the layout audit and the page previews are the only place text collisions show up. If no renderer is available, say so plainly in the report instead of implying the layout was checked. - Never invent an archetype. If no template slide fits the content, say so and ask whether to reshape the content or extend the template — do not approximate.
- Report the warnings you chose to ignore. An overflow warning you decided was fine still belongs in the final report — the user is the one who will see the slide.
- Charts are read-only. Say this out loud when the chosen archetype has one; the template's numbers ship unless the user edits the chart in PowerPoint.
Process
Step 0 · Get the reference template
Ask for the .pptx before anything else if you don't have one:
"레퍼런스 템플릿 pptx를 주세요. deck-builder는 템플릿 슬라이드를 복제하는 방식이라, 템플릿 없이는 만들 수 있는 슬라이드가 없습니다."
Do not proceed on a description of a template, a similar-looking deck, or a promise to supply one later.
Step 1 · Catalog the template
python3 /abs/path/scripts/deck.py catalog \
--template "template.pptx" --output "deck.catalog.md"
Prints every archetype as @s1…@sN with its slots, what the template currently shows,
and a capacity estimate. Read it before anything else.
Step 2 · Map content onto archetypes
Ask the user for the content if you don't have it. Then, before writing any md, show a one-line-per-slide plan:
1. @s1 표지 — 제목 + 부제
2. @s3 요약 — 불릿 3개 + 한 줄 결론
3. @s7 숫자 — 표 4행
Get a nod on the plan. Wrong archetype choice is the expensive mistake, not wrong wording.
Step 3 · Write deck.mdx
---
template: template.pptx
template_hash: 5f84440a3521 # from catalog — pins the deck to the template's structure
output: deck.pptx
---
## @s3
title: 분기 요약
text1:
- 응답 p99 **2.1s → 340ms**
- 배포 실패율 12% → 0.4%
table1:
| 지표 | 이전 | 이후 |
| p99 | 2.1s | 340ms |
pic1: assets/arch.svg
notes: 숫자의 출처를 먼저 말할 것
text5: !drop
Pictures take a fit mode — | fit keeps the whole image, the default fill crops it —
and | transparent knocks a PNG's background out. Slots you leave out keep the template's
content.
Full syntax — slot forms, !drop, notes:, inline emphasis, outline levels, and what
template_hash protects against — is in references/mdx-syntax.md. Read it before
writing the first slide.
Step 3b · Generate the art the deck needs
Write a picture slot's art as an .svg, in the template's colors and at the frame's exact
pt size — both printed by catalog. It becomes source like the rest of the deck and is
rasterized to PNG at build time.
Rules, rationale and a worked example: references/generated-art.md.
Step 4 · Check
python3 /abs/path/scripts/deck.py check --deck deck.mdx
Errors must be fixed. Warnings are judgment calls — surface every one, including the ones you decide to ignore.
| What it measures | Against |
|---|---|
| A table or text running off the slide | the slide edge — an error, naming the rows lost |
| A line too wide for a slot the template keeps to one line | that slot's own frame, in em, so Hangul is not counted as Latin |
| A slot holding far less than the template puts there | the template's own volume — the frame was drawn for that much and the slide opens a hole |
| Text running lower than the design puts it | the template's own line count, and what sits below |
| Crop loss, effective dpi, palette strays, pasted-box borders | the frame, the screen, and the template's palette |
| Text over a picture | the pixels actually behind it: 3:1 for large type, 4.5:1 for body |
A picture drawn after the words it covers is an error — they end up behind the image.
Every estimate here is calibrated against the template's own content rather than an absolute, because most frames are drawn to hold text that already wraps. Margins under about one line are past what a static estimate can resolve: only Step 6 settles those.
Step 5 · Build
python3 /abs/path/scripts/deck.py build --deck deck.mdx [--output out.pptx] [--strict]
The same deck.mdx always produces a byte-identical pptx.
Step 6 · Render and look
python3 /abs/path/scripts/deck.py render --deck deck.mdx
Builds, converts through LibreOffice, writes PNG previews of every page, and audits the
rendered geometry — overlap (two text frames clash), bunched (lines inside one frame
sit closer than that frame's own norm, so text has outgrown its box), off-slide (the
renderer cut it). Clean means clean: the audit compares across frames and measures pitch
against each frame's median, so CJK fonts whose em box exceeds a 100% line do not trip it.
render first says which of the template's typefaces the renderer does not have. A
substituted font rewraps every line, so until those are installed the preview's line breaks
are the substitute's, not the deck's — the fix is to install the font, not to shorten the
words. The pptx itself always names the right faces.
Read the previews for layout, not for spacing. LibreOffice pads the join between CJK and
Latin by default, so 평균 42분 renders as 평균 42 분 in the preview while the pptx holds
the original string. Check <a:t> in the built file before treating spacing as a defect.
Renderer is soffice on PATH or DECK_RENDER_DOCKER=<image>. With neither, render
refuses rather than pretending the layout was checked — say so and fall back to build.
Output Template
Report after a build:
빌드 완료 — <출력 경로>
슬라이드 <N>개 · 템플릿 <이름> · 이미지 <M>개 삽입
렌더 검사 — 겹침 0건 (또는: 3페이지 제목이 본문과 겹칩니다)
아키타입 사용
@s1 ×1 표지
@s3 ×4 본문
확인 필요
· 3번 슬라이드 title 58자 (프레임 ~39자/줄) — 두 줄로 넘어갑니다
· 5번 슬라이드 chart1 — 차트 수치는 템플릿 값 그대로입니다
다음 수정은 deck.mdx만 고치고 다시 build 하세요. 출력 pptx는 손대면 날아갑니다.
What Claude Does / What You Do
| Claude | You |
|---|---|
| Asks for the reference pptx, refuses to proceed without it | Provides the template — mandatory — and the raw content |
Runs catalog, reads the slot map | Reviews the archetype list |
| Proposes the archetype-per-slide plan | Approves or rearranges the plan |
Writes and revises deck.mdx | Edits deck.mdx directly whenever you prefer |
Runs check, reports every warning | Decides whether an overflow warning matters |
Runs render, looks at the previews, reports collisions | Opens the pptx, edits charts if needed |
Limitations
The six that change what you can promise:
| Limit | Consequence |
|---|---|
| No new layouts | Every slide is a clone. Content with no archetype needs the template extended in PowerPoint — say so rather than approximating. |
| A template is mandatory | No built-in design, no fallback. |
| Charts are not writable | build leaves the template's numbers. Use an SVG in a picture slot. |
| Frames never move | Write short and the gap stays; check reports it, only the template can close it. |
| Layout truth needs a renderer | check estimates and cannot resolve margins under a line. Only render sees what collides. |
| Legibility is PNG only | Type over a JPEG or SVG backdrop is unscored; inherited text colors are left alone. |
Full table, and which step catches each one: references/limits.md.
Related Skills
write:plans(document purpose) — develop the content before mapping it onto slidesthink:untangle-thoughts— turn scattered notes into the slide-by-slide structure Step 2 needs