GordenPPTSkill 딥다이브
— AI가 "레이아웃 안 깨고" 진짜 .pptx를 만들어내는 PPT 빌더 스킬

1한줄 요약

2왜 지금 주목받는가

이 저장소는 2026년 5월 27일에 첫 릴리스된 아주 신생 프로젝트다(스타 48개). 그런데도 TrendShift 데일리 4위에 오른 건, 별 개수가 아니라 "언급 모멘텀"으로 순위를 매기는 TrendShift 특성상 지금 개발자 커뮤니티에서 빠르게 회자되고 있다는 뜻이다. 배경에는 세 가지 흐름이 있다.

① "AI 스킬(Agent Skills)" 생태계의 폭발

같은 날 TrendShift 데일리 토픽에서 #AI skills가 3위(10.3k 스타 유입)를 기록했다. Claude Code·Codex 같은 코딩 에이전트에 SKILL.md 한 장으로 능력을 "꽂는" 패턴이 유행하면서, "PPT 만들기 능력을 내 AI에 장착한다"는 컨셉이 정확히 그 파도를 탔다.

② AI PPT 생성의 고질병을 정면으로 해결

아래 표가 이 프로젝트의 존재 이유를 압축한다.

③ "중국 초보자에게 더 적합" — 시나리오 특화

저자 본인의 표현이 "史上最强原生PPT Skill，更适合中国宝宝(역대 최강 네이티브 PPT 스킬, 중국 초보자에게 더 적합)"이다. 템플릿 19종이 중문 직장·당정(党政)·학술 시나리오에 맞춰져 있다 — 분기/연말 업무보고, 述职竞聘(승진 발표), 开题答辩(논문 개제 발표), 당정 사상교육 과제 등. 정보밀도가 높고 "있어 보이는" 国企·대기업풍 슬라이드가 강점이다.

3기술 스택 전체 지도

보통 딥다이브는 백엔드/프론트엔드/인프라로 나누지만, 이 프로젝트는 서버도 화면도 없는 CLI 스킬 패키지다(언어 구성 Python 100%). 그래서 세 축을 이렇게 재정의하는 게 정확하다: ① 실행 엔진(스크립트), ② 데이터 계약(JSON), ③ 배포·갱신 인프라.

① 실행 엔진 — Python 스크립트 6종

② 데이터 계약 — 두 개의 JSON 스키마

이 프로젝트의 두뇌는 코드가 아니라 JSON 두 개다. 각각 버전이 박힌 정식 스키마를 갖는다.

• detail.json (스키마 ppt-template-detail/v1) — 템플릿 제작자가 쓰는 "지도". 각 슬라이드·각 텍스트 칸의 주소·용량·역할을 기술.
• edits.json (스키마 ppt-edit-spec/v1) — 편집하는 AI가 쓰는 "지시서". 어떤 슬라이드를 쓰고, 어느 칸에 무슨 글자를 넣을지.

③ 배포·갱신 인프라 — git 기반 자가 업데이트

④ 외부 도구 의존성

• python-pptx 1.0+ — 필수(pptx 읽기/쓰기).
• LibreOffice(soffice) — 미리보기 렌더링 시에만. pptx를 PDF로 변환.
• Poppler(pdftoppm) — PDF를 페이지별 PNG로.
• 폰트 微软雅黑(맑은 고딕 계열) + fontconfig fallback 체인(WenQuanYi Micro Hei → DengXian → Noto Sans SC → PingFang SC). 최종 pptx는 사용자 PC 폰트로 렌더되므로 폰트 분실 걱정은 없음.

4아키텍처 심화 분석

전체 파이프라인 (모드 A: 내장 템플릿 사용)

핵심 설계 패턴 ① — 두 개의 "기계-AI 계약"

이 프로젝트의 가장 배울 점은 역할을 둘로 쪼갠 데이터 계약이다. detail.json은 "이 템플릿은 이렇게 생겼다"는 사실(정비공의 지도)이고, edits.json은 "그래서 이렇게 바꿔라"는 의도(편집자의 지시서)다. 둘 다 $schema 버전 필드를 달고, 후방호환(v2가 나와도 v1을 계속 파싱) 원칙을 명시한다.

// edits.json — 편집 AI가 만드는 지시서
{
  "template_slug": "minimal-business-summary",
  "selected_slides": [1, 2, 3, 5, 7, 9, 10, 12, 14, 16],
  "edits": [
    {"slide": 1, "slot_id": "cover_title_cn", "new_text": "2026 연말 업무보고"},
    {"slide": 9, "address": {"shape_id": 9, "paragraph": 0, "run": 0},
     "expected_text": "METHOD", "new_text": "PILLARS"}
  ]
}

핵심 설계 패턴 ② — run 단위 치환으로 서식 보존

build_pptx.py의 apply_edit_to_shape()는 문단의 특정 run만 run.text = new_text로 갈아끼운다. run 번호를 안 주면 "문단 전체 교체" 모드가 되는데, 이때도 run 0의 서식은 유지하고 나머지 run만 비운다. 즉 글자는 바뀌어도 폰트·색·자간은 원본 그대로다.

핵심 설계 패턴 ③ — 슬라이드 가지치기(sldIdLst 직접 조작)

prune_slides()는 프레젠테이션의 슬라이드 목록 XML(sldIdLst)에서 고른 슬라이드만 남기고 순서대로 재배열한다. 영리한 점: 새 요소를 만들지 않고 기존 요소 인스턴스를 그대로 재사용한다. 그래야 각 슬라이드의 관계 ID(r:id)가 보존되어 이미지·레이아웃 연결이 끊기지 않는다.

핵심 설계 패턴 ④ — 출框(글자 넘침) 린트

중국어·영어가 섞인 텍스트가 글상자를 넘치는지 빌드 시점에 검사한다. _visual_width()는 한자=1, 영문/숫자≈0.5, 공백≈0.35로 시각 폭을 계산하고, detail.json의 max_chars(글상자 실측 + 20% 여유로 미리 산출)와 비교한다.

• autofit(자동 축소) 글상자는 "soft"로 통과 — 파워포인트가 알아서 줄인다.
• --strict를 주어도 현재(v1.0.17+)는 저장을 거부하지 않고 경고만 출력한다(advisory only). 넘침 발생 시 텍스트를 간결하게 다듬는 것이 원칙.
• 넘칠 때 해법은 "간결하게 표현을 바꿔라. 약간의 넘침은 허용된다. 말줄임표(…/등등) 추가나 글꼴 크기 축소는 금지".

핵심 설계 패턴 ⑤ — type_scale / level 로 "동급 제목 크기 일치"

detail.json 맨 위의 type_scale는 글자 크기 계층표(level 1 = 가장 큼)이고, 각 칸에 level이 붙는다. 규칙: 같은 level의 제목은 모두 같은 크기를 유지해야 한다. 한 곳이 길어 안 들어가면 글꼴을 줄이는 게 아니라 표현을 더 간결하게 줄인다 — 안 그러면 동급 제목 크기가 들쭉날쭉해져 보기 싫어지기 때문. 패턴 ④의 린트가 이 철학을 코드로 강제한다.

핵심 설계 패턴 ⑥ — Progressive Disclosure(점진적 공개)

AI가 토큰을 아끼며 단계적으로만 정보를 연다: SKILL.md(언제·어떻게) → INDEX.md(19종 한 줄 요약) → 후보의 intro.md(압축 소개) → 확정된 1종의 detail.json(상세 좌표). 19개 전체 detail.json을 한꺼번에 읽지 않는다.

핵심 설계 패턴 ⑦ — 자가 업데이트(델타 + 무결성)

apply_update.py는 원격 git을 --depth 1 얕은 클론(LFS 스머지 끔)으로 가져와, 버전 이력에서 내 버전 이후 변경분만 합산해 그 파일만 복사한다. 받은 파일은 manifest.json의 sha256과 대조해 검증한다. "패키지 관리자(npm/apt)를 한 파일로 압축한" 듯한 설계다.

5디렉토리 구조 해부

17개 vs 19개 — 문서 불일치 한 가지

README는 "17 templates"라고 적고, templates/INDEX.md와 updates.json 이력은 19종을 가리킨다. 진실은 19종 — v1.0.2에서 거대 합집합 템플릿(report-template-massive)을 3종(models/charts/reports)으로 쪼개면서 늘었고, README 문구만 갱신이 덜 됐다. v1.0.8 변경 이력에도 "스크립트 목록/템플릿 수 정정"이 적혀 있어, 활발히 다듬어지는 중임을 보여준다.

6학습 포인트 (기술별)

7하드웨어·시스템 요구사항

이 스킬은 모델을 돌리지 않는다(텍스트 생성은 당신이 쓰는 외부 AI가 함). 그래서 요구사항이 매우 가볍다.

8직접 해볼 수 있는 실습 과제

🟢 입문 — 템플릿 하나로 5장짜리 PPT 빌드

저장소를 클론하고 minimal-business-summary 하나를 골라, selected_slides에 5장만 넣고 edits.json을 손으로 작성해 build_pptx.py를 돌려본다. 결과 pptx를 파워포인트에서 열어 레이아웃이 정말 안 깨졌는지 눈으로 확인.

python3 scripts/build_pptx.py \
    templates/minimal-business-summary/template.pptx \
    edits.json out/final.pptx \
    --detail templates/minimal-business-summary/detail.json

🟢 입문 — --dry-run 과 --strict 체험

같은 명령에 --dry-run을 붙여 "실제로 어떤 칸을 바꿀 계획인지"만 출력해보고, 일부러 아주 긴 제목을 넣은 뒤 --strict로 돌려 출框 경고 메시지(시각 폭 vs 용량, advisory only)를 읽어본다. 패턴 ④·⑤가 체감된다.

🟡 초급 — detail.json 한 페이지 읽어내기

minimal-business-summary/detail.json을 열어 page_roles(cover/agenda/section_divider/content/ending)와 한 페이지의 text_slots(slot_id·address·max_chars·editable)를 해독한다. "이 칸은 왜 editable=false인가?"를 스스로 설명해보기.

🟠 중급 — 모드 B로 "내 PPT"를 탐사하기

detail.json이 없는 임의의 .pptx를 python-pptx로 직접 열어, 각 슬라이드의 shape/paragraph/run 구조를 덤프하고 render_slides.py로 PNG를 떠본다. 그런 뒤 명시적 address만으로 표지 제목을 교체하는 edits.json을 써본다(원본 파일은 절대 수정 금지, 새 파일로 출력).

🔴 고급 — 자가 업데이트 메커니즘 이식

apply_update.py의 collect_delta()·git_apply() 로직을 떼어, 자신의 다른 프로젝트(예: 프롬프트 모음 저장소)에 "버전 비교 → 변경 파일만 받기 → sha256 검증" 자가 업데이트를 붙여본다. updates.json·manifest.json·VERSION 3종 세트를 직접 설계하는 게 핵심.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 공식 자료

• GitHub 저장소: github.com/GordenSun/GordenPPTSkill
• AI 진입 문서: SKILL.md
• 템플릿 색인(19종): templates/INDEX.md
• 데이터 계약 정의: references/pptx-edit-schema.md
• 변경 이력: CHANGELOG.md · updates.json
• TrendShift 페이지: trendshift.io/repositories/41729

핵심 기술 문서

• python-pptx: python-pptx.readthedocs.io
• Office Open XML(OOXML) 개요: en.wikipedia.org/wiki/Office_Open_XML
• LibreOffice: libreoffice.org · Poppler: poppler.freedesktop.org
• WenQuanYi Micro Hei(대체 폰트): wenq.org

관련 흐름 — AI Skill 생태계

• Anthropic Skills: github.com/anthropics/skills
• Claude Code: github.com/anthropics/claude-code
• TrendShift #AI skills 토픽: trendshift.io/topics/ai-skills