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. - Write in the voice
catalogmeasured. Its## Voicesection is the reference's own sentence endings, length, English-term and digit share, footnote mark. Match them; do not default to your own register. - 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 and the caller has no render rule of its own, finish with
render, notbuild— the layout audit and the page previews are the only place text collisions show up. A caller that renders only when told (manage, a workspace README) decides; then say the layout was not checked this time. 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.
- Keep the template's gaps. Every
임계 침범(check) andzone/drift(render) goes in the report; fix it by shortening or another archetype, never by moving a frame to make room.place:moves a frame only when the user asks, or to close the gap a!dropleft — never as a cure for overflow. All of a deck's layout lives indeck.mdx(place:,[text]{#hex|sup},captions:,panel_margin:—references/mdx-syntax.md), never in a script run after the build. - 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"
What the catalog prints (slots, per-slot budget, critical zones) and how font widths are found: references/render-and-check.md — read before writing any slot; write to the budget.
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
A whole deck.mdx as a worked example, paragraph formats ([text]{n}, <br>), extract, picture fit and | transparent, and textN_plusK cloning: references/mdx-syntax.md — read when writing a slide for the first time or when a slot needs more than plain text.
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 (table, and how font widths are resolved): references/render-and-check.md.
A picture drawn after the words it covers is an error — they end up behind the image.
How much slack check allows, and when to trust 추정: references/render-and-check.md — read when a warning sits within a line of the limit.
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. The build ends with the shared final check
(office_render.py): an "AI-generated content may be incorrect" in alt text is removed; an AI tool in the
properties, an AI phrase or a TODO / [확인 필요 in the text is a warning, never deleted — tell the user
each one. Before calling a deck submittable run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/office_render.py final-check [--dir build] [--allow "Claude Code,Codex"] [--author NAME]: a verdict per file, non-zero on a finding.
Step 6 · Render and look
python3 /abs/path/scripts/deck.py render --deck deck.mdx
What render does: references/render-and-check.md — read before running it. --deck may be
relative. After every render, not only on a warning, run render-review on the PDF and previews.
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
Six limits change what you can promise: no new layouts, a mandatory template, charts that are not writable, frames that never move, layout truth that needs a renderer, and legibility scored on PNG only. Read the wording and consequence of each before promising any of them.
Full table, and which step catches each one: references/limits.md.
Related Skills
write:prd(document purpose) — develop the content before mapping it onto slidesthink:untangle-thoughts— turn scattered notes into the slide-by-slide structure Step 2 needs