Communitygithub.com

HTML 슬라이드를 편집 가능한 PPTX로 변환

HTML 슬라이드 덱을 진정으로 편집 가능한 PPT/PPTX 파일로 변환합니다. 텍스트는 스크린샷이 아닌 네이티브 파워포인트 텍스트 상자로 유지됩니다. 에이전트 스킬 (Claude Code / Cursor / Codex / opencode) + 순수 Python CLI를 지원합니다.

HTML 슬라이드를 편집 가능한 PPTX로 변환란 무엇인가요?

이 스킬은 HTML로 작성된 슬라이드 덱을 완전히 편집 가능한 Microsoft PowerPoint (.pptx) 파일로 변환하는 전문 도구입니다. 텍스트는 네이티브 파워포인트 텍스트 상자로 유지되어 최종 사용자가 내용을 자유롭게 수정할 수 있습니다. Claude Code, Cursor, Codex, opencode와 같은 주요 AI 에이전트 플랫폼에서 에이전트 스킬로 사용하거나, 또는 `python convert.py input.html` 명령어로 독립형 Python CLI로 실행할 수 있습니다. 이 도구는 다단계 파이프라인(입력 분석, 측정, 조립, 글꼴 임베딩, 구조적 자체 검사, 시각적 감사)을 사용하여 변환 정확도를 보장합니다. HTML에서 사용된 Google Fonts를 자동으로 다운로드 및 하위 집합화하여 임베드하며, CJK 문자에 대해 Noto Sans/Serif SC를 지원하고, `--only-slides` 플래그를 통한 증분 재실행을 지원하여 감사 반복 중 효율성을 높입니다. 또한 시각적 감사에 사용할 렌더러를 감지하고, 사용자가 PowerPoint COM 또는 LibreOffice를 설치하도록 안내하며, 발견된 문제를 추적하고 최소한의 HTML 수정을 적용하는 엄격한 감사 및 수정 절차를 따릅니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓OpenCode
npx skills add Hasasasa/html-to-editable-pptx

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

html-to-pptx

트리거 시점

사용자가 다음과 같은 의도를 표현할 때:

  • "이 HTML/웹 덱을 PPT/pptx로 변환해 줘"
  • "HTML 슬라이드를 만들었는데 동료에게 ppt 파일을 줘야 해"
  • "발표 현장에서 브라우저를 열기 어려워서 ppt 파일이 필요해"
  • HTML 파일 경로를 주면서 ppt/pptx/프레젠테이션/슬라이드를 언급할 때

호출

<skill_dir>은 이 스킬의 설치 경로입니다 (보통 ~/.claude/skills/html-to-pptx/, Windows에서는 %USERPROFILE%\.claude\skills\html-to-pptx\). 아래 명령에서 <skill_dir>을 실제 경로로 바꾸거나, 먼저 cd <skill_dir> 한 다음 python convert.py ... 를 실행하세요.

python <skill_dir>/convert.py <input.html>
  • 기본 출력은 입력 파일과 같은 디렉토리에 <input>.pptx로 생성됩니다.
  • 글꼴은 완전히 주문 제작됩니다: 변환 시 HTML에서 사용된 글꼴을 Google Fonts에서 가져와 하위 집합화하여 임베드하며, %LOCALAPPDATA%\html-to-pptx\fonts\ 또는 ~/.cache/html-to-pptx/fonts/에 캐시되므로 같은 글꼴은 다음에 즉시 재사용됩니다.
  • HTML에 CJK 문자가 포함된 경우 자동으로 Noto Sans SC + Noto Serif SC 시드를 추가합니다 (처음에는 약 40MB / ~30초 다운로드 및 Regular/Bold 정적 인스턴스 생성 후 캐시됨).
  • Google Fonts에 없는 패밀리는 뷰어 시스템 글꼴로 대체되며 경고가 출력됩니다.
옵션설명
--out <path>사용자 정의 출력 .pptx 경로
--keep-screenshots각 페이지의 HTML 참조 스크린샷 및 preflight.json을 함께 유지
--no-embed-fonts글꼴 임베딩 건너뜀. 파일 크기는 작아지지만 다른 환경에서 시스템 글꼴로 대체됨
--no-preflight1단계 위험 사전 검사 비활성화
--no-verify5a단계 구조적 자체 검사 비활성화
--no-visual-audit5b단계 시각적 감사 자료 생성 비활성화. 일상적으로 비활성화하지 마세요
--install-user-fonts자동으로 파싱된 비-CJK 글꼴을 사용자 글꼴 디렉토리에 설치 (WPS에서 올바르게 렌더링되도록). Win/macOS/Linux를 지원합니다. 사용자에게 반드시 먼저 물어봐야 합니다. 아래 '설정 확인' 섹션 참조
--only-slides N,N,N증분 재실행. 쉼표로 구분된 페이지 번호 (1부터 시작). 측정은 지정된 페이지만 실행 + 이전 라운드의 캐시된 측정값과 병합; 조립/임베드는 전체 실행; 5a단계는 지정된 페이지만 렌더링; 5b단계는 지정된 페이지의 비교 이미지만 재구성 — 다른 모든 페이지는 이전 라운드 캐시를 재사용. 감사 반복 전용. 아래 '증분 재실행' 섹션 참조
--cleanup변환하지 않음. input.pptx 옆의 audit / measurement / preflight 작업 파일을 삭제하고 .pptx와 audited.html만 남깁니다. 최종 전달 전에 사용. 아래 '워크플로우' 마지막 단계 참조

작업 복사본 (원본 HTML 불변)

처음 python convert.py <input>.html 실행이 완료되면, convert.py가 자동으로 <input>.audited.html 복사본을 원본 HTML과 같은 디렉토리에 생성합니다. 메커니즘:

  • 모든 감사 수정은 audited.html에 적용되며, 원본 HTML은 변경되지 않습니다.
  • 이후 convert 실행 (--only-slides 포함)은 <input>.audited.html을 입력으로 사용하며, 출력은 여전히 <input>.pptx입니다 (자동으로 .audited 접미사 제거).
  • audited.html이 이미 존재하면 재사용되며 덮어쓰지 않습니다 (이전 라운드의 수정 사항 유지).
  • 에이전트가 실수로 원본 HTML을 입력으로 전달하면, convert.py가 내부적으로 감지하여 audited.html로 전환합니다.
  • cleanup은 audited.html을 삭제하지 않습니다 (.pptx와 함께 전달 가능한 부산물로 간주).
  • 처음부터 다시 시작하려면 audited.html을 수동으로 삭제한 후 재실행하세요.

설정 (.config.local.toml)

스킬 루트 디렉토리에 있는 선택적 로컬 설정 파일이며, gitignored되고 사용자별로 하나씩 존재합니다. 현재 세 가지 유형의 설정이 있습니다:

[fonts]
auto_install = "ask"   # "yes" 자동 설치, "no" 절대 설치 안 함, "ask" 에이전트가 질문

[cleanup]
default = "clean"      # "clean" 워크플로우 마지막 단계에서 자동 cleanup, "keep" 감사 산출물 유지

[audit]
mode = "ask"           # "triage" / "page" / "manual" / "ask" 에이전트가 질문
  • 파일 / 키가 없으면 기본값을 사용합니다 (위와 동일).
  • 템플릿: <skill_dir>/.config.local.toml.example
  • fonts.auto_install은 convert.py가 강제로 읽고 적용합니다 (=yes이면 자동으로 --install-user-fonts 추가, =no이면 자동으로 무시).
  • cleanup.default는 워크플로우 마지막 단계에서 에이전트가 읽고 행동을 결정합니다.
  • audit.mode는 첫 번째 convert 전에 에이전트가 확인합니다; 5b단계 후 이 값에 따라 검토가 수행됩니다:
    • "triage" → 메인 에이전트가 audit_contact_*.png 개요 이미지를 보고 분류한 후, 선정된 페이지의 단일 이미지를 sub-agent에게 보내 토큰을 절약합니다.
    • "page" → 모든 대상 페이지에 대해 sub-agent가 단일 slide_NN_compare.png를 검토하여 가장 엄격하게 적용합니다.
    • "manual" → 검토 자료만 생성하고 사용자에게 수동 검토를 맡깁니다. 사용자가 문제를 보고한 후 수정합니다.
    • "ask" 또는 누락 → 에이전트가 AskUserQuestion을 통해 선호도를 수집한 후 이 항목을 다시 씁니다 (기본값).
  • 최초 사용: 에이전트가 AskUserQuestion을 통해 fonts.auto_install과 audit.mode를 수집한 후 직접 이 파일을 씁니다 — 사용자가 수동으로 만들 필요가 없습니다.

설정 확인 (첫 번째 convert 전에 완료)

첫 번째 convert 전에 두 가지 설정을 확인해야 합니다: fonts.auto_install과 audit.mode. 프로세스는 동일하며, 트리거 조건과 질문 방식만 다릅니다.

일반 프로세스

각 설정은 독립적으로 아래 순서대로 결정됩니다:

  1. <skill_dir>/.config.local.toml을 읽고 해당 필드를 확인합니다:
    • 유효한 ask가 아닌 값 → 해당 값대로 진행하며, 세션 내에서 다시 묻지 않습니다.
    • ask 또는 파일 / 필드 누락 → "트리거 판단 + ask"로 이동합니다.
  2. CLAUDE.md / 전역 지시에 동등한 값이 명시되어 있으면, 명시된 값대로 진행하고 config에 다시 씁니다 (단일 진실 공급원 유지).

트리거 후 AskUserQuestion으로 한 번 질문하며, 두 가지 모두 수행해야 합니다:

  • <skill_dir>/.config.local.toml의 해당 필드에 사용자 응답을 씁니다 (ask는 쓰지 않습니다. 그렇지 않으면 다음 세션에서 다시 묻게 됩니다).
  • 현재 세션에서는 응답에 따라 진행합니다.

config를 쓸 때: 파일이 없으면 → Write로 전체 파일을 저장합니다 ([fonts] [cleanup] [audit] 세 부분 템플릿). 파일이 이미 있으면 → Edit으로 한 줄을 replace합니다 (이 필드만 변경). Write로 전체 파일을 다시 쓰지 마세요. 그렇지 않으면 사용자의 다른 사용자 정의 키가 손실됩니다.

같은 세션에서 두 설정이 모두 트리거되면 → 하나의 AskUserQuestion으로 합쳐서 한 번에 질문합니다.

fonts.auto_install — 글꼴 설치

PowerPoint COM slide.Export()와 WPS Office는 pptx에 임베드된 원시 TTF를 읽지 않습니다 — 감사 렌더링과 WPS 모두 시스템 글꼴로 대체됩니다. 사용자 글꼴 디렉토리에 설치하면 둘 다 시스템 글꼴을 사용합니다. 디렉토리 (모두 사용자 수준이며 수동으로 삭제 가능):

  • Windows: %LOCALAPPDATA%\Microsoft\Windows\Fonts\ + HKCU 레지스트리
  • macOS: ~/Library/Fonts/
  • Linux: ~/.local/share/fonts/ + fc-cache -f

트리거 판단: HTML <head>의 <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / <style> 내 font-family:에 나타난 글꼴 이름을 확인합니다:

  • 트리거: 모든 GF / 자체 호스팅 글꼴 (Bricolage Grotesque, DM Sans, Inter, Space Grotesk, Caveat 등)
  • 트리거 안 함: 시스템 글꼴 화이트리스트만 사용 (Arial, Times New Roman, Helvetica, Helvetica Neue, Courier, system-ui, -apple-system, BlinkMacSystemFont, SF Pro, Microsoft YaHei, SimSun, PingFang, Hiragino)

응답에 따라: 동의 → --install-user-fonts 추가; 거부 → 추가하지 않음.

audit.mode — 시각적 검토 모드

세 가지 모드 triage / page / manual (의미는 위의 '설정' 섹션 참조). 세션의 첫 번째 convert 전에 항상 판단 (HTML 내용에 의존하지 않음). AskUserQuestion은 객관식이며, 옵션은 세 가지 모드입니다.

워크플로우 (필수)

convert.py 실행이 완료되었다고 해서 전달이 완료된 것은 아닙니다. 전체 프로세스:

convert.py (첫 라운드 자동 cp <input>.audited.html, 모든 수정은 이 복사본에 적용)
  → 5a단계 구조적 자체 검사 (OOXML 스캔, 힌트 제공)
  → 5b단계 시각적 감사 자료 생성 — PowerPoint COM 또는 LibreOffice 렌더러 필요
  → `audit.mode` 읽고 검토 방식 결정: triage / page / manual
  → [에이전트 감사]
        triage 모드: 메인 에이전트가 contact sheet 읽고 분류 → sub-agent가 선정 페이지 단일 이미지 검토 → 병합하여 audit_findings.md 작성
        page 모드: 전체 sub-agent가 단일 페이지 검토 → 병합하여 audit_findings.md 작성
        manual 모드: 감사 자료를 사용자에게 전달하고, 사용자의 수동 피드백을 기다림
  → finding별로 최소한의 로컬 수정 적용, 대상은 audited.html (아래 '수정 규율' 참조)
  → 한 배치의 finding 수정 후 `convert.py <input>.audited.html --only-slides <수정된 페이지 번호>` + 새 페이지에 대해서만 재검토 (아래 '증분 재실행' 참조)
  → 모든 페이지가 OK 또는 LOW만 남음
  → [HTML 안티패턴 / 새로운 OOXML 경계 발견 시] lessons-learned에 축적, 아래 'HTML 문제 및 OOXML 경계 축적' 참조
  → `<skill_dir>/.config.local.toml`의 `cleanup.default` 읽기:
        "clean" (기본값) → 바로 `python convert.py <out>.pptx --cleanup` 실행, 사용자에게 묻지 않음
                          정리 후 디렉토리에 남는 파일: <input>.html (원본, 변경 없음) + <input>.audited.html (수정 버전) + <out>.pptx
        "keep"        → cleanup 건너뜀, 감사 산출물 모두 유지
  → .pptx 경로를 사용자에게 전달 (audited.html은 수정된 HTML로 함께 전달)

벡터 우선 원칙 (필수)

PPT 네이티브 text/shape/line으로 표현할 수 있는 내용은 편집 가능성을 유지하는 것이 우선입니다: 일반 배경색, 일반 사각형 테두리, 단일 선, 단순한 직사각형/타원, 단순한 ::before/::after 와이어프레임은 모두 PPT shape으로 처리되어야 합니다.

deco_snapshot은 OOXML로 표현하기 어려운 장식에만 사용됩니다 (적중 조건 + 전체 단계 정의 + 스크린샷/벡터 레이어 협력 메커니즘은 references/supported-css.md 참조). 일반 선, 차트 축선, 단순한 테두리를 편의상 통째로 스크린샷 처리하지 마세요 — PPT 편집 가능성을 해칠 뿐만 아니라 이후 로컬 수정을 어렵게 만듭니다.

렌더러 요구 사항 (5b단계 전제 조건)

5b단계 시각적 감사는 .pptx를 PNG로 렌더링해야 하며, 다음이 필요합니다:

  • PowerPoint COM (Windows + Office + pywin32), 또는
  • LibreOffice (크로스 플랫폼, pip install pdf2image 필요)

둘 중 하나만 있으면 감사를 실행할 수 있습니다. convert 출력에 [self-check] 건너뜀: 사용 가능한 pptx 렌더러를 찾을 수 없음 메시지가 보이면, 둘 다 설치되지 않은 것입니다 — 이 경우 감사는 비교 이미지를 생성하지 않으며, 5b단계는 건너뜁니다.

이 경우 에이전트는 반드시 사용자에게 물어봐야 합니다 (감사되지 않은 pptx를 조용히 전달하지 마세요):

"사용자 컴퓨터에 PowerPoint도 LibreOffice도 설치되어 있지 않아 시각적 감사를 실행할 수 없습니다. PPT에 눈에 띄지 않는 시각적 버그가 있을 수 있습니다. 세 가지 선택지가 있습니다:

  1. LibreOffice 설치 (권장, 크로스 플랫폼, 2-3분 소요): winget install LibreOffice.LibreOffice (Windows) / brew install --cask libreoffice (mac) / apt install libreoffice (Linux), 그 다음 pip install pdf2image, convert 재실행
  2. 감사를 건너뛰고 바로 전달 (PPT에 시각적 버그가 있을 위험 감수)
  3. Office가 이미 설치된 다른 컴퓨터에서 재실행"

사용자가 1을 선택하면 → 설치가 완료될 때까지 기다린 후 재실행; 2를 선택하면 → --no-visual-audit 플래그를 추가하여 실행하고, 위험을 고지한 후 전달; 3을 선택하면 → 현재 디렉토리와 HTML을 사용자에게 보냅니다.

시각적 감사 모드 (config, 전제: 5b 실행됨)

시각적 검토를 실행하기 전에 <skill_dir>/.config.local.toml의 [audit].mode를 읽습니다. 정상적으로는 첫 번째 convert 전에 위의 '설정 확인'을 통해 질문이 완료되어야 합니다. 만약 여기서 모드가 여전히 "ask"라면 (에이전트가 질문을 놓친 경우), 즉시 위의 '설정 확인' 섹션에 따라 사용자에게 질문한 후 계속 진행합니다.

각 모드의 구체적인 의미는 위의 '설정' 섹션을 참조하십시오; 여기서는 적용 시나리오만 나열합니다:

모드적용
triage기본값, 토큰 절약
page최종 전달 전, 중요 고객, 사용자가 가장 엄격하게 요구할 때
manual사용자가 직접 보고 싶을 때

triage의 역할 분담은 매우 명확합니다: 1라운드 contact pass = 메인 에이전트가 직접 썸네일을 보고 분류 (저렴함, 컨텍스트에 이미 소스 HTML / 5a단계 / preflight 포함); 2라운드 detail pass = 선정된 페이지를 sub-agent가 단일 페이지 비교 이미지를 보도록 전송. 썸네일만으로 HIGH/MID finding을 판단할 수 없습니다; finding을 보고하려면 반드시 2라운드 sub-agent의 단일 페이지 확인을 거쳐야 합니다.

감사 분배 및 비교 이미지 읽기 규칙

page 모드는 모든 페이지가 Claude Agent(...) sub-agent로 병렬 디스패치됩니다. triage 모드는 2라운드 선정 페이지만 sub-agent로 전송되며; 1라운드 contact sheet는 메인 에이전트가 직접 읽고 sub-agent를 보내지 않습니다.

메인 에이전트가 비교 이미지를 직접 읽는 시나리오는 다음 다섯 가지로 제한됩니다:

  • triage 1라운드 audit_contact_*.png 개요 이미지 읽어 분류
  • 대상 수정의 검증 라운드: 이번 라운드의 새 페이지가 ≤ 2개이고 변경 사항이 전역 CSS와 관련되지 않은 경우 → 메인 에이전트가 직접 새 페이지의 단일 이미지를 읽어 기존 finding을 재확인하고 해당 페이지의 새로운 회귀를 스캔하며, sub-agent를 보내지 않습니다 (sub-agent 한 라운드에 2-3분 소요, 직접 읽으면 몇 초). 새 페이지가 더 많거나 전역 변경이 있는 경우 여전히 sub-agent 사용.
  • finding 설명이 모호하거나 소스 코드와 충돌하여 위치를 파악할 수 없는 경우, 해당 단일 페이지 slide_NN_compare.png를 읽습니다.
  • sticky가 적중되기 전에 확인하기 위해 단일 페이지를 읽습니다.
  • 사용자가 특정 페이지를 지목하여 피드백한 경우 단일 페이지를 읽습니다.

이 외에는 페이지별로 비교 이미지를 읽지 않습니다.

batch는 wall-clock 최적화를 위해 작게 나누어 병렬 처리합니다 (sub-agent가 큰 이미지를 직렬로 읽는 것이 지연의 주요 원인입니다; 여러 개의 작은 batch를 병렬로 보내는 것이 하나의 큰 batch보다 두 배 이상 빠릅니다):

슬라이드 수전략
≤ 21개의 batch
3-20batch당 2페이지, 모두 병렬 전송
> 20batch당 3페이지 (에이전트 총 수 제어)

전체 sub-agent 호출 템플릿 + 체크리스트 + findings 형식은 <out>_audit/audit_prompt.md를 참조하십시오. 여러 개의 Agent(..., run_in_background: true, subagent_type: "general-purpose") 호출을 메인 에이전트의 같은 메시지에 넣어야 병렬로 실행됩니다.

sub-agent는 findings 텍스트만 반환하며 (page 모드는 각 대상 페이지의 ## page NN 블록 포함; triage 세부 검토 배치는 각 확대 검토 페이지의 블록 포함), 메인 에이전트가 통합하여 audit_findings.md에 씁니다 — 동시에 쓰면 서로 덮어씁니다.

각 finding은 반드시 안정적인 요소의 짧은 이름을 지정하고, "HTML 반쪽의 실제 상태; PPT 반쪽의 차이"를 설명해야 합니다. PPT가 HTML에 비해 새로 추가하거나 확대한 시각적 문제만 보고합니다; HTML 반쪽 자체에 이미 있는 문제는 변환 finding에 포함되지 않습니다.

sub-agent와 병행하는 메인 에이전트 준비 (필수)

page 모드 또는 triage 2라운드 detail sub-agent를 시작할 때, Agent 호출은 run_in_background: true를 사용하고, 같은 메시지에서 동시에 다음을 전송합니다:

Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 5-9", prompt: ...)
Read(file_path: "<deck>/template.html")
Read(file_path: "<skill_dir>/references/lessons-learned.md")
Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
     output_mode: "content", -n: true)

각 sub-agent prompt에는 이 배치의 slide_NN_compare.png 절대 경로, 덱 HTML 경로, lessons-learned.md 경로 (적용 범위는 위의 '시각적 감사 모드' 섹션 참조)가 직접 포함되어야 합니다; 메인 에이전트의 Read/Grep 출력이 자동으로 sub-agent에 전달된다고 가정하지 마세요.

"findings와 관계없이 항상 사용되는" 준비만 전송하십시오 — findings를 예측하여 HTML을 미리 수정하지 마세요.

수정 규율 (finding 대상, 근본 원인 추적 금지)

audit_findings.md를 받은 후, 한 라운드에서 이번 라운드의 모든 finding을 다 수정한 후, 한 번에 convert + audit을 재실행하십시오 — 하나씩 수정하고 실행하지 마세요. 한 라운드 = 한 배치의 HTML 편집 + 한 번의 convert + 한 번의 audit.

findings를 받은 후:

  • 일반적으로 비교 이미지를 직접 읽지 않습니다 (findings에 이미 증상이 명시되어 있습니다); 세 가지 예외는 위의 '감사 분배 및 비교 이미지 읽기 규칙' 섹션을 참조하십시오.
  • measure.py / assemble.py / 스킬 내 코드를 읽어 근본 원인을 찾지 않습니다.
  • 바로 audited.html을 열고 finding별로 하나씩 수정합니다.

각 finding에 대해 최소한의 로컬 HTML 수정을 수행합니다:

  • 각 finding은 "이것을 사라지게 하는" 한 군데만 수정하고, 다음 finding으로 넘어갑니다 (HTML 계속 수정, convert 재실행 안 함).

  • "왜 글꼴이 대체되었는지 / 왜 레이아웃이 어긋났는지"의 근본 원인을 추적하지 않습니다.

  • "내가 .footer도 절대 위치로 바꾸는 게 좋겠다"와 같은 finding 목록 외의 최적화를 하지 않습니다.

  • finding 간 구조적 리팩토링을 하지 않습니다 ("모든 슬라이드의 font-family를 명시적으로 선언" ≠ 단일 finding의 최소 수정).

  • 동일한 finding이 연속 두 라운드 (이전 라운드 + 현재 라운드) 모두 나타나면 → sticky가 적중됩니다. 사용자에게 알리고 중단하며, 수정 범위를 넓히지 마십시오. 판단 키 = (페이지 번호, 시각적 요소 짧은 이름):

    • 표현 / 심각도 / HIGH↔MID 전환은 판단을 초기화하지 않습니다. 예: (page 5, take 글자 크기)가 round 6에서 "약간 작음"으로, round 7에서 "심각하게 부족함"으로 설명되어도, 동일한 sticky 키이므로 round 7에서 적중됩니다.
    • "페이지 번호 + 요소"가 모두 중복되지 않아야 새로운 sticky 키로 간주됩니다.
    • 라운드 간 복구: round 6에 나타나고, round 7에 사라지고, round 8에 다시 나타나면 → sticky로 간주하지 않습니다 (round 7에 없었으므로 문제가 수정된 것으로 간주, round 8은 새로운 회귀).
    • 적중 = 이번 라운드에서 해당 finding을 수정하지 않음, 스킬 경계 후보로 사용자에게 알리고, 이번 라운드의 다른 finding은 정상 수정.

    구현: 각 라운드 audit_findings.md를 병합하고 Edit을 시작하기 전에, 먼저 이전 라운드의 audit_findings.md를 읽고 (첫 라운드는 없음) 쌍별 비교를 수행합니다 — 이번 라운드와 이전 라운드 모두 나타난 키가 적중됩니다. 적중된 finding은 별도로 사용자에게 판단을 맡기고, 이번 라운드의 편집 큐에 포함되지 않습니다.

이번 배치의 finding 수정이 완료되면 한 번에 python convert.py <input>.audited.html --only-slides <수정된 페이지 번호>를 실행합니다.

판단 기준: diff 라인 수 ≤ findings 수 × 3 라인. 이 정도를 넘으면 "과도하게 수정"하고 있는 것입니다.

증분 재실행 (--only-slides)

감사 2라운드부터 사용됩니다. 첫 라운드는 전체 실행입니다.

python convert.py <input>.audited.html --only-slides 2,7,12

증분은 measure / 5a단계 렌더링 / 5b단계 비교 이미지를 나열된 페이지만 + 캐시 누락 페이지만 실행합니다; assemble / embed_fonts는 여전히 전체 실행입니다. audit_index.json에 incremental_mode: true, fresh_indices, cached_indices, 각 페이지의 fresh: true/false가 표시됩니다.

증분 라운드의 감사 대상 페이지는 fresh_indices만 사용합니다. page 모드는 이 페이지들을 직접 분배합니다; triage 모드는 먼저 이 페이지들 내에서 분류한 후, 선정된 페이지를 sub-agent에 보냅니다.

전제 조건: 이전 라운드의 <out>_audit/ 디렉토리가 있어야 합니다. 캐시 누락 시 자동으로 전체 실행으로 대체됩니다; HTML 페이지 수 변경 시 자동 감지되어 전체 measure로 대체됩니다.

--only-slides를 사용할 수 없는 경우 (시각적 영향이 나열된 페이지를 벗어나거나, 캐시 위음성일 경우):

  • 전역 CSS (<style>, 루트 선택자, .slide 공통 스타일) 변경
  • 글꼴 추가/삭제 (@import, font-family 선언 변경)
  • 덱 수준 토큰 (배경, 테마 색상, 간격) 변경
  • 다른 페이지 레이아웃에 영향을 미치는 전역 변수 변경

이런 경우에는 플래그 없이 전체 재실행합니다. 판단이 불확실하면 → 전체 재실행이 항상 안전합니다.

HTML 문제 및 OOXML 경계 축적 (필수)

당신의 역할은 호출 + 사용법 축적이며, 스킬을 수정하는 것이 아닙니다. 스킬 내부 버그를 발견하면 measure.py / assemble.py를 직접 수정하지 마십시오.

다음 두 가지 유형만 축적합니다:

1. HTML 작성 문제 (사용자의 HTML으로 인한 변환 왜곡)

카테고리판단수행 작업
단일 케이스 (이 덱에만 해당, HTML 한두 줄 수정으로 해결)단일 페이지 특례HTML 소스를 직접 수정; 축적하지 않고, 알리지 않음
일반 HTML 안티패턴 (누구나 비슷한 HTML을 작성하면 발생)덱 간 공통HTML 수정 + references/lessons-learned.md의 "HTML 작성 회피" 영역에 축적

2. OOXML 표현력 경계 (PowerPoint / OOXML이 자연스럽게 지원하지 않음)

대부분의 장식용 CSS (backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / ::before ::after 장식 용법 — 빈 content + bg-image / box-shadow 등)는 이미 '커버리지 전략'의 hasComplexDecoration에 의해 자동으로 deco_snapshot으로 캡처됩니다 — HTML을 수정할 필요가 없습니다. ::before ::after string content (content: "↑" 등)는 텍스트 채널을 통해 처리됩니다. 자세한 내용은 references/supported-css.md의 1단계를 참조하십시오.

여전히 HTML workaround가 필요한 진정한 경계 (OOXML 텍스트 계층이 기본적으로 표현할 수 없는 것):

경계대체 경로
컬러 이모지 (COLR/CPAL 폰트)Twemoji SVG <img>, img 채널을 통해 임베드
background-clip: text 텍스트 그라데이션인라인 <svg><text fill="url(#grad)">, SVG 채널을 통해 처리

이러한 유형에 부딪히면 → HTML을 수정하여 대체 경로를 사용하고 references/lessons-learned.md의 "OOXML 경계" 영역에 축적합니다.

위 표에 없는 새로운 CSS 미지원을 발견하면 → 먼저 hasComplexDecoration이 누락되었는지 확인 (트리거 조건 한 줄 추가만으로 해결 가능), HTML을 수정하지 마십시오. 자세한 내용은 references/supported-css.md의 "새로운 지원 추가 표준 절차"를 참조하십시오.

스킬 내부 버그처럼 보이는 경우 처리 방법 (수정하거나 축적하지 않음)

같은 CSS 패턴을 가진 증상이 다른 덱에서도 발생하고, 알려진 OOXML 경계에 속하지 않는 경우 → 이는 스킬 추상화가 부족한 것입니다. 스킬 코드를 직접 수정하지 마십시오. 다음 두 가지 작업을 수행합니다:

  1. 현재 덱에서 HTML 쪽 workaround를 적용하여 finding을 수정하고, 사용자가 전달 가능한 PPT를 받을 수 있도록 합니다.
  2. 명확히 사용자에게 알립니다: "스킬 내부의 일반적인 버그로 보이는 것을 발견했습니다: [증상 + 트리거 CSS 패턴 + 현재 workaround]. 작성자에게 이슈로 등록하여 스킬이 measure/assemble에서 이 패턴을 더 일반적으로 처리할 수 있도록 제안하는 것이 좋습니다."

축적 위치: 로컬 복사본 + 업스트림 템플릿

references/lessons-learned.md는 사용자별 독립적인 로컬 작업 복사본입니다 (gitignored). 처음 convert.py를 실행할 때 local_config.seed_lessons_learned()가 템플릿 lessons-learned.md.example (committed)에서 자동으로 복사본을 만듭니다. 메커니즘은 .config.local.toml과 동일합니다.

  • 에이전트의 조사/축적은 모두 로컬 lessons-learned.md를 읽고 씁니다 — 자유롭게 추가/수정/정리 가능, git 노이즈 없음
  • 로컬 복사본은 절대 업스트림에 의해 덮어쓰이지 않습니다 — git pull은 .example 템플릿만 가져오고 작업 복사본은 건드리지 않습니다.
  • 특정 축적을 업스트림에 보내려면: 작성자가 수동으로 entry를 lessons-learned.md.example에 복사한 후 commit; 선택적으로 큐레이션하며, 전체를 푸시하지 않습니다.
  • 로컬 업무 / 특정 고객 전용 작성법 → 로컬 복사본에 직접 작성하면 되며, 업스트림으로 올라가지 않습니다.
  • lessons 항목은 재사용 가능한 증상, 트리거 패턴, 회피 규칙만 작성합니다; 구체적인 로컬 파일 이름, 템플릿 이름, 페이지 번호, 고객 이름 또는 소스 파일 이름은 작성하지 마십시오. 구체적인 구현 위치, 명령 및 코드 세부 사항은 commit / issue / 메인 스킬 문서에 남깁니다.

트리거: 일반 HTML 안티패턴 / OOXML 경계에 부딪히면 → 로컬 lessons-learned.md의 해당 테이블에 추가합니다. 매번 convert할 때마다 다시 읽으며, 즉시 적용됩니다.

커버리지 전략 (한 문장)

스킬 내부에서는 모든 CSS를 네 가지 출력 단계로 번역합니다: 벡터 텍스트 → 벡터 모양 → 래스터 장식 (deco_snapshot) → 미디어 직접 전송. 간단한 bg-color / border / border-radius는 처음 두 단계 (편집 및 검색 가능)로 처리되며, box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / 비대칭 둥근 모서리 / 잘린 컨테이너 + 회전 자식 등은 hasComplexDecoration에 적중되어 세 번째 단계로 처리됩니다 (래스터는 장식 픽셀만 캡처하고, 텍스트는 항상 벡터로 유지되어 스크린샷 위에 그려짐).

전체 단계 정의 / 트리거 조건 / 새 지원 추가 가이드 (벡터 우선 → 스크린샷 최후 수단) → references/supported-css.md.

파이프라인

[1 입력 식별/사전 검사] → [2 측정] → [3 조립] → [4 글꼴 임베딩] → [5a 구조적 자체 검사] → [5b 시각적 감사]
   preflight.py    measure.py   assemble.py   embed_fonts.py  self_check.py    visual_audit.py

각 단계의 동작 / 반가정 규칙 / 종료 어설션 / 새 템플릿 체크리스트 → references/methodology.md.

5b단계는 <out>_audit/ 디렉토리를 생성합니다 (비교 이미지 + contact sheet + audit_index.json + audit_prompt.md). 픽셀 diff를 하지 않습니다 — 숫자는 로컬 버그에 둔감하고 잘못된 확신을 줍니다; 시각적 판단은 audit.mode에 따라 triage / page / manual로 진행됩니다. 렌더러가 없으면 5b단계는 건너뛰고, 위의 '렌더러 요구 사항' 섹션에 따라 사용자에게 질문합니다.

호출 전

…

[번역을 위해 생략됨]

관련 스킬