Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-pptx

hyper-pptx

Verified

Use this skill when the user asks to build, edit, or read a PowerPoint deck - create a .pptx from an outline or analysis, add slide transitions or element animations, change text or fonts in a deck someone else made, remove slides, or open a .pptx and report what each slide says. Write a typed JSON spec, render with a bundled engine to a .pptx plus checked slide images, or inspect an existing deck before touching it. Do not use for slide images only, PDF-only output, Google Slides, or Keynote.

FileKindSize
SKILL.ko.mdmarkdown17.8 KB
SKILL.mdskill md15.9 KB
assets/evals/hyper-pptx-cases.jsonlother20.8 KB
assets/examples/media/city-night.jpgbinary82.6 KB
assets/examples/media/detail-square.jpgbinary109.2 KB
assets/examples/media/hero-landscape.jpgbinary30.2 KB
assets/examples/media/team-wide.jpgbinary24.4 KB
assets/examples/media/workspace-tall.jpgbinary23.5 KB
assets/examples/proposal.deck.jsonconfig3.9 KB
assets/examples/report.deck.jsonconfig3.2 KB
assets/examples/showcase.deck.jsonconfig9.1 KB
assets/preview/viewer.cssother1.5 KB
assets/preview/viewer.jsscript37.4 KB
assets/runtime/layout.jqother63.7 KB
assets/runtime/pptx-package.jqother59.5 KB
assets/runtime/workbook.jqother4.6 KB
references/motion.ko.mdmarkdown10.1 KB
references/motion.mdmarkdown9.4 KB
references/pptx-internals.ko.mdmarkdown10.5 KB
references/pptx-internals.mdmarkdown9.2 KB
references/research-charts.ko.mdmarkdown5.9 KB
references/research-charts.mdmarkdown5.3 KB
references/research-design.ko.mdmarkdown7.3 KB
references/research-design.mdmarkdown6.9 KB
references/research-images.ko.mdmarkdown5.3 KB
references/research-images.mdmarkdown4.7 KB
references/research-verification.ko.mdmarkdown6.2 KB
references/research-verification.mdmarkdown5.6 KB
references/spec-format.ko.mdmarkdown18.9 KB
references/spec-format.mdmarkdown17.2 KB
rules/deck-narrative.ko.mdmarkdown4.7 KB
rules/deck-narrative.mdmarkdown4.3 KB
rules/layout-and-typography.ko.mdmarkdown12.4 KB
rules/layout-and-typography.mdmarkdown11.0 KB
rules/render-and-verify.ko.mdmarkdown9.3 KB
rules/render-and-verify.mdmarkdown8.4 KB
scripts/edit-deck.shexecutablescript8.2 KB
scripts/inspect-deck.shexecutablescript14.1 KB
scripts/render-deck.shexecutablescript25.1 KB

references/pptx-internals.ko.md

View on GitHub
# PPTX 내부 구조

덱이 복구 안내 없이 열려야 할 때, 편집이 원본 서식을 건드리지 않아야 할 때, 또는 이 패키지가 라이브러리 대신 OOXML을 직접 쓰는 이유를 누가 물을 때 이 파일을 읽습니다.

## Contents

- 패키지는 파트를 담은 압축 파일
- 슬라이드마다 필요한 여섯 파트
- 빈 레이아웃 하나에 절대 좌표를 쓰는 이유
- 파워포인트가 복구를 제안하는 경우
- 모션이 슬라이드 파트에서 사는 자리
- 실행 분할, 텍스트 편집이 빗나가는 이유
- 이 패키지가 일부러 하지 않는 일

## 패키지는 파트를 담은 압축 파일

`.pptx`는 OPC 패키지입니다. 경로로 이름 붙인 XML 파트를 담은 압축 파일이고, 각 파트의 미디어 타입을 선언하는 `[Content_Types].xml`이 하나 붙습니다. 규칙이 둘 나오고, 둘 다 결정적입니다.

모든 파트는 `[Content_Types].xml`에 있어야 합니다. 타입이 선언되지 않은 슬라이드는 XML이 멀쩡하고 파일도 있어도 파워포인트에 보이지 않습니다.

모든 관계 대상이 실제로 있어야 합니다. `.rels` 파트가 `rId2` 같은 짧은 아이디를 경로에 연결합니다. 대상 파일이 없으면 패키지는 여는 순간 깨지고, 렌더링 단계에서는 아무 문제가 없어 보입니다.

압축 항목의 순서와 시각은 상관없습니다. 그래서 렌더러는 모든 시각을 1980-01-01로 고정하고 `zip -X`를 씁니다. 같은 spec이 같은 바이트를 만들고, 두 빌드의 차이를 비교하는 일이 의미를 가집니다.

## 슬라이드마다 필요한 여섯 파트

| 파트 | 담는 것 | 지웠을 때 측정된 결과 |
|---|---|---|
| `ppt/slides/slideN.xml` | 도형, 배경 | 열기 실패: `no relationship with key 'rId11'` |
| `ppt/slides/_rels/slideN.xml.rels` | 레이아웃, 노트, 차트, 이미지 관계 | 열리지만 `slide_layout`을 읽을 때 `KeyError: no relationship of type slideLayout` |
| `ppt/notesSlides/notesSlideN.xml` | 발표자 노트 | 열리고 노트 창이 비어 있음 |
| `ppt/notesSlides/_rels/notesSlideN.xml.rels` | 슬라이드로 돌아가는 연결 | 열리고 노트도 읽힘 |
| `ppt/presentation.xml`의 `sldId` | 순서와 슬라이드 관계 | 슬라이드 하나가 줄어 열리고, 파트는 압축 안에 남음 |
| `[Content_Types].xml`의 `Override` | 슬라이드 미디어 타입 | 슬라이드가 아닌 파트로 열림: `'Part' object has no attribute 'slide'` |

이 결과는 정상 덱에서 파트를 하나씩 지우고 python-pptx로 다시 열어 측정했습니다. 여섯 중 둘은 크게 실패하고 나머지는 조용히 실패합니다. 에이전트에게는 조용한 쪽이 더 나쁩니다. 파일은 멀쩡해 보이고, 사람이 열거나 다른 도구가 덱을 훑을 때에야 드러나기 때문입니다.

그래서 `edit-deck.sh --drop-slide`는 여섯 개를 모두 지운 뒤 XML 파트와 관계를 다시 검사합니다. 덱이 열리는 상태여도 남은 고아 파트는 실패로 셉니다.

## 빈 레이아웃 하나에 절대 좌표를 쓰는 이유

템플릿 기반 작성기는 자리표시자를 채우고 위치, 크기, 상속을 레이아웃에 맡깁니다. 회사 템플릿에 맞는 덱이 나오고, 동시에 예상 밖의 일도 나옵니다. 마스터에서 18포인트를 상속받은 글자, 레이아웃이 바뀌면 튀는 제목 상자, 마스터 안쪽 여백이 0.05인치가 아니라 0.1인치라 넘치는 본문 같은 일입니다.

이 패키지는 반대로 합니다. 빈 레이아웃 하나, 마스터 하나, 테마 하나를 넣고 모든 도형을 절대 EMU 좌표로 씁니다. 결과는 이렇습니다.

- 작성기가 정한 좌표가 항상 이깁니다. 상속이 없습니다.
- 같은 해석 결과가 PPTX와 HTML 미리보기를 함께 만들므로 미리보기가 파일과 어긋날 수 없습니다.
- 브라우저에서 계산한 배치 검사가 .pptx에 대한 검사로도 유효합니다.
- 덱이 사용자의 템플릿을 물려받지 않습니다. 그래서 기존 덱 편집은 `edit-deck.sh`로만 합니다. 원본 패키지를 그대로 두고 이름 붙인 부분만 건드리는 방식입니다.

EMU는 1인치에 914400이라 13.333 × 7.5인치 슬라이드는 12192000 × 6858000입니다. 포인트 크기는 다른 단위입니다. `sz` 속성과 `spaceBefore`는 100분의 1포인트이고 브라우저는 픽셀을 쓰므로 `px = pt * 12700 / 9525`로 바꿉니다.

## 파워포인트가 복구를 제안하는 경우

| 증상 | 원인 |
|---|---|
| 열 때 복구 안내 | 파트에 `[Content_Types].xml` 항목이 없음 |
| 열 때 복구 안내 | `.rels` 대상 경로가 없음 |
| 복구 뒤 슬라이드가 사라짐 | `sldId`가 지운 관계를 가리킴 |
| 그림이 안 보임 | 이미지 관계 없는 `r:embed` 아이디, 또는 선언되지 않은 확장자 |
| 차트에 데이터가 없음 | 차트 파트에 범주와 값 캐시가 빠짐 |
| 노트 창이 빔 | `notesSlide` 파트는 있는데 슬라이드에서 연결하지 않음 |
| 전환 뒤 복구 안내, 이어서 슬라이드가 사라짐 | ECMA-376 효과 요소가 아닌 `p:transition` 자식 |
| 애니메이션 뒤 복구 안내 | `p:cTn id` 중복, 또는 그런 도형이 없는 `p:spTgt spid` |
| 사진이 엉뚱하게 잘려 보임 | 0에서 1을 벗어난 값을 쓴 `srcRect` |

`render-deck.sh`는 모든 XML 파트의 정상 형식, 모든 관계 대상의 존재, 아래 모션 규칙 셋을 직접 검사하고, 끊긴 참조가 있는 패키지는 내보내지 않고 1로 끝냅니다. 복구 안내 자체는 검사하지 못합니다. 이 기기에 파워포인트가 없어 그 줄은 규격을 근거로 한 추론입니다.

## 모션이 슬라이드 파트에서 사는 자리

`p:sld`는 끝에 선택적 `p:timing`을 두고, 그 앞에 선택적 `p:transition`을 둡니다. 기록된 파트에서는 순서가 이렇습니다. 도형 트리를 담은 `p:cSld`, `p:clrMapOvr`, `p:transition`, `p:timing`. `transition` 요소는 `p:cSld` 밖에 있습니다. 도형 트리 안에 쓴 전환은 파워포인트가 무시하고, 슬라이드는 오류 없이 그냥 즉시 넘어갑니다.

애니메이션 대상이 `n`개인 슬라이드에는 타이밍 트리가 하나 있고, 그 `p:tnLst`가 클릭 묶음마다 `p:par`를 하나씩 담습니다. 묶음 안에서 대상마다 `p:par` 하나와 `p:cTn` 행 하나가 붙고, 행의 `p:childTnLst`가 실제 동작을 담습니다.

id는 덱이 아니라 슬라이드마다 유일합니다. 두 슬라이드가 모두 `id="1"`을 써도 됩니다. `1`부터 `3`은 슬라이드 자체의 `p:cTn` 뿌리 사슬이 쓰므로 애니메이션 행은 `4`에서 시작합니다. 행마다 id 네 개를 잡고 클릭 묶음 래퍼가 하나를 쓰는 구조이며, 그래서 중복 id 검사가 슬라이드 단위로 돕니다.

`p:spTgt`는 `p:cNvPr id`를 지목하고, 그 번호는 도형 트리에서 그 도형이 가진 번호와 같습니다. 이 번호는 배치 단계에서 한 번만 부여합니다. 애니메이션 대상과 대상이 가리키는 도형이 어긋날 수 없게 하려는 것이고, 번호를 두 패스에서 따로 계산하면 없는 도형을 지목하는 대상이 기록됩니다.

사진 파트도 같은 방식입니다. 처음 `n`개의 그림 관계가 `rId10`부터 하나씩 붙고, 각 `p:pic`은 파일을 다시 쓰지 않고 `a:srcRect`에 자기 자르기를 담습니다. 관계 id 순서는 spec에 사진이 나온 순서이므로, 첫 사진을 지우는 편집은 나머지 번호를 당깁니다.

스키마와 효과 전반은 `motion.md`에 있습니다.

## 실행 분할, 텍스트 편집이 빗나가는 이유

워드프로세서는 문단을 하나 이상의 실행으로 저장하고, 실행은 서식이 하나로 정해진 구간입니다. `카드 인증 단계 실패 47%`는 일부가 굵게 처리되거나 붙여넣기, 맞춤법 검사를 거치면 실행 세 개로 나뉠 수 있습니다. 그러면 눈에 보이는 문구 전체를 찾아도 아무것도 걸리지 않습니다.

그래서 `edit-deck.sh`는 추측하지 않고 못 찾았다고 보고합니다. 빗나갔을 때 정직한 선택지는 셋입니다.

1. 한 실행 안에 들어 있는 더 짧은 문자열로 바꾸고 반복합니다.
2. 편집이 많으면 새 spec으로 슬라이드를 다시 씁니다.
3. 파워포인트에서 열어 `--replace` 호출을 여러 번으로 나눕니다.

억지로 실행을 합치지 않습니다. 합치면 서식이 바뀌고 실행이 나뉘어 있던 이유도 사라집니다.

## 이 패키지가 일부러 하지 않는 일

- 기존 덱의 템플릿 상속, 자리표시자 재사용, 테마 교체를 하지 않습니다.
- 글꼴을 포함하지 않습니다. 요청한 글꼴은 읽는 사람의 컴퓨터에 있어야 합니다.
- SmartArt를 쓰지 않습니다. 전환과 요소 애니메이션은 쓰되, 이름과 효과를 닫힌 목록으로 제한하고 XML을 스키마와 대조한 것만 냅니다. 재생은 여전히 확인하지 못했고 `motion.md`에 그렇게 적혀 있습니다.
- 모션 경로, 글자 단위 빌드, 마스터 애니메이션은 넣지 않습니다.
- 그림을 만들지 않습니다. 예제의 자리 그림은 사진이 아니라 평면 도형입니다.
- 외부 엔진으로 `.pptx`를 렌더링하지 않습니다. 미리보기는 이 패키지의 렌더러이고, 파일 구조를 기준으로 검사받는 쪽입니다. 반대가 아닙니다.

## Sources

> 확인 2026-11-13.

| Claim | Source |
|---|---|
| OPC 패키지 구조와 `[Content_Types].xml` 역할 | <https://learn.microsoft.com/en-us/office/open-xml/presentation/structure-of-a-presentationml-document> |
| 슬라이드, 노트, 관계 파트 | <https://learn.microsoft.com/en-us/office/open-xml/presentation/working-with-presentations> |
| 차트 파트가 범주와 값을 캐시로 가짐 | <https://learn.microsoft.com/en-us/office/open-xml/presentation/working-with-charts> |
| DrawingML 실행 구조와 텍스트가 실행으로 나뉘는 이유 | <https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.text> |
| EMU와 포인트 변환 | <https://learn.microsoft.com/en-us/office/open-xml/presentation/structure-of-a-presentationml-document> |

### 근거 등급

`LOCAL` - 파트 제거 표의 모든 줄은 2026-11-13에 렌더링한 덱에서 파트를 정확히 하나씩 지우고 python-pptx로 다시 열어 측정했습니다. 복구 안내 줄은 규격을 근거로 한 추론입니다. 이 기기에 파워포인트가 없습니다.
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall