이미지를 편집 가능한 PPT로 (Claude Code 포트)
번들 editppt 런타임을 사용하여 시각적 슬라이드를 분해, 재구성, 유효성 검사 및 편집 가능한 .pptx로 조립합니다. 입력은 하나 이상의 이미지, PDF, 또는 이미지 기반 PPT/PPTX일 수 있습니다. 출력은 항상 하나의 .pptx이며, 입력 페이지 순서대로 각 페이지가 하나의 슬라이드가 됩니다.
<skill-root> 아래는 이 SKILL.md가 포함된 디렉토리를 의미합니다.
이 스킬의 구성
이 파일은 **조정자(orchestrator)**인 당신이 읽습니다. 페이지 수준 작업은 생성된 프롬프트에 따라 페이지 재구축자(page reconstructors)(배경 하위 에이전트 또는 단일 페이지의 경우 당신 자신)가 수행합니다. 각 규칙은 하나의 권위 있는 장소를 가집니다 — 추측하지 말고 포인터를 따르십시오:
prompts/page-worker.md— 페이지 재구축자 템플릿: 소유권 경계, 읽기 경로, 실행 순서, 필수 출력물, 반환 형식.scripts/build-page-worker-prompt.py에 의해 채워집니다.references/cli-helper.md—editppt설치 확인, 명령어 트리, 구문. 명령어를 선택할 때 읽습니다.references/manifest-schema.md— 모든 실행/페이지 아티팩트에 대한 JSON 계약. 실행 또는 페이지 파일을 쓰거나 검증할 때 읽습니다.references/page-decision-tree.md— 배경 vs. 이미지 자산 vs. 네이티브 텍스트/도형/테이블이 되는 것, 텍스트 힌트 사용법, 최종 자체 점검, 수정-vs-경고. 페이지 재구축자가 이를 읽습니다. 당신은 거의 필요하지 않습니다.
Claude Code 런타임 매핑
업스트림 스킬은 Codex를 대상으로 합니다. 다음은 여기서 작동하도록 만든 대체 항목입니다. 이는 참조 문서가 Codex 해당 항목을 언급하는 모든 곳에 적용됩니다.
| 업스트림 (Codex) 개념 | Claude Code에서 |
|---|---|
내장 image_gen.imagegen + 이미지 모델 자산 시트 | claude-native 백엔드로 대체됨. Claude는 비트맵을 볼 수 있지만 생성할 수 없으므로 아이콘/일러스트레이션을 SVG로 추적하고, 사진을 직사각형 원본 영역으로 유지하며, 로컬에서 깨끗한 베이스를 인페인트합니다 (references/page-decision-tree.md 섹션 2.4). 항상 --image-backend claude-native로 prepare하십시오. 절대 builtin-imagegen을 사용하지 마십시오. |
CLI 이미지 API (editppt image generate/edit) | 선택적 업그레이드 전용이며, editppt doctor --check-api가 준비된 백엔드를 보고하고 객체가 네이티브 소스에 적합하지 않을 때 사용됩니다. 필수 사항이 아닙니다. |
view_image | 이미지 파일 경로 (source.png, text_hints.png, 줌 및 .compare.png 이미지, preview.png, split_assets_contact.png) Read |
| 페이지 워커 / 하위 에이전트 생성 | Agent 도구, subagent_type: "general-purpose", run_in_background: true, name: "ppt-<page_id>" (예: ppt-page_003). |
--agent-id를 위한 워커 ID | 에이전트에 부여한 동일한 이름 (ppt-page_003); 단일 페이지 로컬 모드의 경우 main. |
| 워커 대기 | 배경 에이전트는 완료되면 알림을 보냅니다. 루프에서 폴링하지 마십시오. |
| 수정 사항을 워커로 보내기 | 워커의 이름으로 SendMessage를 사용하여 컨텍스트를 유지합니다. |
| 샌드박스 / 네트워크 승인 | Claude Code 권한 프롬프트. 로컬 RapidOCR 힌트를 사용하는 claude-native 실행은 외부 호출을 전혀 하지 않습니다. PaddleOCR은 토큰이 구성된 경우에만 호출됩니다 (editppt prepare / editppt run hints). editppt image generate/edit은 선택적 업그레이드가 사용되는 경우에도 외부로 호출합니다. |
시작 계약 (Entry Contract)
이러한 조정자 수준 규칙은 여기에 한 번 명시됩니다.
- CLI 우선.
editppt는 필수 런타임입니다.editppt --help가 실패하면<skill-root>/cli에서references/cli-helper.md의 사전 실행 확인(Pre-Run Check)을 사용하여 설치하십시오 (uv가 있을 때uv tool install --force --editable <skill-root>/cli를 선호하고, 그다음pipx, 그다음pip --user). 그런 다음editppt doctor를 실행하십시오. - CLI를 통해서만 상태 관리.
editppt prepare <input...>으로 시작하십시오. 그 후에는editppt명령어를 통해서만 모든 상태 전환을 진행하십시오. 실행/페이지 상태 JSON을 직접 작성하지 마십시오. 이렇게 하면 실행을 결정적이고 재개 가능하게 유지할 수 있습니다. - 페이지를 재구축하는 주체. 정확히 하나의 페이지가 있는 실행은
editppt run dispatch --local이 이를 주장한 후 로컬 모드에서 당신이 재구축합니다. 여러 페이지 실행은 배경 페이지 워커(페이지당 하나)에 의해 재구축됩니다. 여러 페이지 아티팩트를 직접 재구축하지 마십시오. 각 페이지는 많은 컨텍스트(이미지, 매니페스트, 수정 루프)를 소모하며, 이를 별도의 워커에 유지하는 것이 오케스트레이션 컨텍스트를 사용 가능하게 유지하고 페이지가 병렬로 실행될 수 있게 합니다. - 아티팩트 소유권.
--local주장 이후 단일 페이지 로컬 모드를 제외하고는manifest.json,page.pptx,preview.png,split_assets_contact.png,validation.json또는page_result.json을 작성하지 마십시오. 로컬 모드는 워커와 동일한 페이지 프롬프트, 참조, 출력 및run record검증을 따릅니다. - 이미지 백엔드. 아래 "Claude Code의 이미지 백엔드"를 참조하십시오. 허용된 소스가 객체를 재현할 수 없으면 페이지는 대략적인 도형이나 아이콘 크롭을 대체하는 대신 검증에 실패합니다 (
references/page-decision-tree.md섹션 2). - 승인된 외부 호출. 슬라이드를 편집 가능한 PPT로 변환하는 요청은 해당 변환에 필요한 OCR 호출(및 구성된 경우 이미지-API 호출)을 승인합니다. 단, 사용자가 로컬 전용 처리를 요청하거나 입력을 기밀로 표시한 경우는 예외입니다. 작업 로컬 페이지 이미지, 프롬프트, 마스크 및 참조 이미지만 전송하고 관련 없는 파일이나 자격 증명은 전송하지 마십시오. 타사 엔드포인트는 사용자가 구성하거나 명명한 경우에만 허용됩니다.
- 자율성. 일상적인 재구성, 구성된 폴백 및 페이지 로컬 수정을 확인 게이트 없이 실행하십시오. 사용자만 제공할 수 있는 것(OCR 토큰 결정, 누락된 입력)에 대해서만 사용자를 위해 중지하십시오. 사용자에게 디버그를 요청하는 대신 구체적인 차단 항목을 보고하십시오.
- 객체 결정은
references/page-decision-tree.md를 따릅니다. 결정론적 검증은 구조 게이트이며 객체-소스 결정을 포기하지 않습니다. manifest.json은 권위 있는 페이지 빌드 소스입니다.run record는page.pptx를 이에 대해 검증하고run finalize는 기록된 매니페스트에서 덱을 재구축합니다.
자격 증명 위생
비밀(PaddleOCR 토큰, 선택적 이미지-API 키)은 사용자가 채팅에 붙여넣으면 대화록에 남게 됩니다. 사용자에게 ! 접두사를 사용하여 직접 구성 명령어를 실행하도록 제안하여 값이 CLI로 직접 전달되도록 하십시오. 예:
! editppt config --paddle-ocr-token <token>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1 # 선택적 이미지-API 업그레이드
어쨌든 사용자가 채팅에 키를 붙여넣으면 editppt config로 저장하고 다시 에코하지 마십시오. CLI는 출력에서 이를 마스킹합니다. 프로젝트, 실행 디렉토리 또는 스킬 디렉토리에 키를 절대 작성하지 마십시오.
Claude Code의 이미지 백엔드
Claude는 비전이 있지만 이미지 생성 기능이 없으므로 모든 실행은 claude-native 백엔드를 사용합니다: editppt prepare <input...> --image-backend claude-native. 페이지 재구축자는 references/page-decision-tree.md 섹션 2.4에 따라 각 객체의 소스를 선택합니다:
- 아이콘, 로고, 배지, 손으로 그린 표시, 플랫 일러스트레이션 — Claude는 이를 SVG로 추적합니다 (
editppt image zoom후editppt image svg). PPTX는 실제 SVG를 포함하므로 PowerPoint에서 사용자가 색상을 다시 지정하거나 **도형으로 변환(Convert to Shape)**을 사용하여 개별 패스를 편집할 수 있습니다.这使得这些 객체가 업스트림 스킬의 비트맵 자산보다 더 편집 가능하게 만듭니다. - 사진, 스크린샷, 텍스처 블록 — 직사각형 원본 영역으로 유지됩니다 (
editppt image photo-region). 벡터 추적은 이를 만화로 바꿀 수 있습니다. - 재구축된 텍스트 뒤의 복잡한 배경 — 로컬 인페인팅으로 정리됩니다 (
editppt image inpaint).
사용자에게 이미지 API를 요청하지 마십시오. editppt doctor --check-api가 우연히 준비된 백엔드(Codex 로그인 또는 구성된 키)를 표시하는 경우, 워커는 복잡한 배경 위의 사진 컷아웃과 같이 네이티브 소스에 잘 맞지 않는 객체에 대해 선택적 업그레이드로 editppt image generate/edit을 사용할 수 있습니다. 페이지 내의 자산 명령어는 직렬로 실행됩니다.
워크플로
1단계: 준비 (Prepare)
references/cli-helper.md의 준비 예제와 references/manifest-schema.md의 실행/페이지 파일 설명을 읽으십시오.
editppt prepare <input...> --image-backend claude-native
기본 --out-root를 유지하십시오. 현재 디렉토리 아래에 작업 실행 디렉토리 output/image-to-editable-ppt/<job-id>/를 생성합니다. 사용자가 결과를 원하는 폴더를 가리키지 마십시오. 해당 폴더는 최종 덱만 받아야 합니다 (4단계). 그 후에는 deck_manifest.json, page_jobs.json, notes_manifest.json이 있어야 하며, 각 페이지에는 source.png와 page_request.json이 있어야 합니다.
Prepare는 또한 페이지별 텍스트 힌트(text_hints.json/text_hints.png)를 작성합니다. 토큰이 없으면 로컬 RapidOCR에서 제공되며, 텍스트를 기기에서 읽고 업로드하지 않으므로 사용자에게 아무것도 요청하지 마십시오. Prepare가 기하학 전용 builtin-ink 백엔드(RapidOCR 사용 불가)를 보고하는 경우에만 페이지를 디스패치하기 전에 사용자에게 한 번 요청하십시오: https://aistudio.baidu.com/account/accessToken의 무료 토큰을 editppt config --paddle-ocr-token <token>으로 저장하면 힌트가 내용을 인식하게 됩니다(텍스트 위치만 측정하는 것이 아니라 텍스트를 읽음). editppt run hints <run>는 현재 실행의 힌트를 그 자리에서 다시 생성합니다. 무료 개인 할당량은 이 스킬에 충분합니다. 사용자의 선택을 기다리십시오. 거부하면 오프라인 힌트로 계속 진행하고 다시 요청하지 마십시오.
사용자가 Indra OCR(또는 더 빠른/대체 로컬 OCR)을 요청하면 editppt config --text-hints-backend indra를 실행하고 [indra] 추가 기능을 사용하여 CLI를 다시 설치하십시오 (references/cli-helper.md). Indra의 모델 가중치에는 상업적 사용을 제한하는 수정된 OpenRAIL-M 라이선스가 적용된다는 점을 한 번 언급하십시오. 테스트에서 RapidOCR이 슬라이드 텍스트를 더 완전하게 읽었으므로 자체적으로 전환하지 마십시오.
토큰이 구성되었지만 권한 프롬프트나 네트워크 오류로 인해 OCR이 폴백된 경우, 이는 선호되는 품질 경로가 아닙니다. 호출을 허용하고 페이지 재구축 전에 editppt run hints <run>을 다시 실행하십시오. 사용자가 OCR을 거부한 후, 허용된 OCR 시도가 실제 서비스 이유로 실패한 후, 또는 사용자가 로컬 전용 처리를 요청한 경우에만 오프라인으로 계속 진행하십시오.
2단계: 페이지 재구축 또는 디스패치
반복적으로 호출하고 반환된 stage에 따라 행동하십시오:
editppt run next <run> --json
stage=rebuild_page_locally (정확히 하나의 페이지). 이를 주장한 다음 직접 재구축하십시오:
python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <abs-run-dir>/pages/<page_id>/worker-prompt.mdeditppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md --local- 생성된 프롬프트를
Read하고 해당 페이지 디렉토리 내에서 따라가며 워커가 생성할 것과 동일한 출력을 생성하십시오.
stage=dispatch_pages. 제안된 각 페이지에 대해 이 순서대로:
- 위의 스크립트로 프롬프트를 빌드하십시오.
Agent도구로 워커를 생성하십시오 —subagent_type: "general-purpose",run_in_background: true,name: "ppt-<page_id>",description: "Rebuild <page_id> as editable PPT", 그리고prompt는 다음과 같이 설정하십시오:You are a page reconstructor for the image-to-editable-ppt skill (Claude Code port). Read <abs-run-dir>/pages/<page_id>/worker-prompt.md and follow it exactly. Claude Code notes: view images with the Read tool; you cannot generate bitmaps, so non-text visuals come from page-decision-tree.md section 2.4 (SVG traces, photo regions, local inpaint); run shell commands with Bash. Do not touch files outside your page directory.- 생성이 성공한 후에만:
editppt run dispatch <run> --page <page_id> --agent-id ppt-<page_id> --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md
배치의 제안된 모든 페이지를 단일 메시지에 생성하여 동시에 실행되도록 하십시오. --out 및 --prompt-file은 절대 경로여야 페이지 디렉토리가 두 번 추가되지 않습니다. 동시성 슬롯은 page_jobs.json.max_concurrent_pages (기본값 6)에서 가져옵니다.
stage=wait. 디스패치된 페이지는 활성 리스(lease)이지 유휴 슬롯이 아닙니다. 완료 알림을 기다리십시오. 워커가 느리거나 조용하다고 해서 중지, 재설정 또는 교체하지 마십시오. 복잡한 페이지는 정당하게 10분 이상 걸릴 수 있습니다.
stage=configure_backend. 제안된 builtin-imagegen/CLI 계약 대신 editppt run backend <run> --mode claude-native를 실행하십시오.
3단계: 기록 (Record)
워커의 완료 알림이 도착하면 (또는 로컬 페이지를 완료하면):
editppt run record <run> --page <page_id> --agent-id <id>
이는 page.pptx를 manifest.json에 대해 검증하고, 배치된 객체에 소스-픽셀 좌표가 없거나, 매니페스트가 독립적으로 페이지를 재구축할 수 없거나, validation.json에 최상위 passed: true가 없으면 페이지를 거부합니다. 그런 다음 editppt run next로 돌아가십시오.
수정 (Repairs). 기록이 실패하면 실패 증거를 읽고 페이지 소유자가 영향을 받은 아티팩트만 수정하고, 재검증(editppt page validate, references/cli-helper.md 참조)하고 다시 기록하게 하십시오. 여러 페이지 모드에서는 관련 없는 매니페스트 또는 테이블 오류를 수정하기 위해 규정을 준수하는 자산을 다시 생성하지 마십시오. 새 워커를 생성하는 대신 기존 워커(ppt-<page_id>)에 증거를 SendMessage하십시오. 이미 페이지 컨텍스트와 검증된 자산을 보유하고 있습니다.
재설정 (Reset) 페이지가 새로 실행되어야 하는 경우에만: 워커가 종료 상태로 종료되었거나, 사용자가 취소했거나, 반복적인 연결 가능성 시도가 페이지 로컬 진행 상황을 보여주지 않는 경우. 느린 것은 손실된 것이 아닙니다. 차단 원인을 수정한 후:
editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost
재설정은 페이지를 pending 상태로 되돌립니다. 새로운 프롬프트와 워커로 2단계를 재개하십시오. 기존 아티팩트는 출처 및 선택적 재사용을 위해 유지됩니다.
입력 또는 조건을 변경한 후에만 재시도하십시오. 동일한 실패 호출을 반복하지 마십시오. 실제 전제 조건이 누락된 경우 진행 상황을 보존하고 구체적인 차단 항목을 보고하십시오. 출력이 검사를 통과하면 변경되지 않은 시각적 QA를 반복하지 말고 계속 진행하십시오.
4단계: 마무리 (Finalize)
run next가 finalize 단계를 반환하면:
editppt run finalize <run>
Finalize는 기록된 각 pages/page_NNN/manifest.json에서 페이지 순서대로 덱을 재구축하고, .pptx 발표자 노트를 변경하지 않고 복사하며, 결과를 검증합니다: 유효한 패키지, 슬라이드 수 = 입력 페이지 수, 올바른 PDF/PPTX 페이지 순서, 변환되지 않은 원시 텍스트 없음. 최종 .pptx는 output/image-to-editable-ppt/<job-id>/<input-slug>_editable.pptx에 기록되고 실행 디렉토리에 링크됩니다. 강력히 권장: 사용자에게 최종 덱을 원하는 위치에 복사하도록 요청하십시오.
5단계: 정리 (Clean up) (선택 사항)
output/image-to-editable-ppt/<job-id>/ 작업 디렉토리는 여러 번 재사용할 수 있지만 많은 공간을 차지할 수 있습니다. 완료하고 사용자가 덱을 저장한 후:
editppt run clean <run>
실행의 결과 외부 덱과 기록된 매니페스트를 제외한 모든 페이지 아티팩트를 제거합니다. 정리된 실행은 포워드 전용입니다: 페이지 검증 데이터가 없으므로 파일 복구, 재디스패치 또는 기록이 불가능합니다. 사용자가 명시적으로 요청하지 않는 한 정리하지 마십시오.
에이전트 없음, UI 없음
이 스킬은 개발자 도구로 설계되었습니다. 모든 것은 사용자가 시작한 요청의 맥락에서 이루어지며, 빌드 시스템의 일부이거나 UI를 렌더링하지 않습니다. 작업을 완료하지 않고 완료를 암시하지 마십시오.