목차(클릭하세요)
원고를 넣으면 편집 가능한 PPTX를 만드는 AI 에이전트용 스킬 패키지. 설치부터 제작·수정·검증까지 안내함.
[ 깃허브 저장소]
1. pptx_Agent 소개와 주요 특징
1-1. 도구 개요
•
pptx_Agent는 Claude Code·Codex 같은 AI 코딩 에이전트에서 사용하는 PPT 제작 스킬 패키지임.
•
별도 웹서비스에 로그인해 슬라이드를 만드는 방식이 아니라, 저장소 폴더를 AI 에이전트에서 열고 자연어로 제작을 요청하는 방식임.
•
자료 분석·디자인 확인·슬라이드 작성·품질 검사·PPTX 내보내기를 정해진 절차에 따라 진행함.
•
학교 회의 자료·수업 설명 자료·연수 발표 자료를 제작하는 용도로 활용 가능함.
1-2. 입력 자료와 결과물
•
PDF·DOCX·Markdown·웹 URL·텍스트 등을 원고로 활용할 수 있으며, 주제만 제공해 제작을 요청하는 방식도 안내됨.
•
결과물은 PowerPoint에서 텍스트와 도형을 개별적으로 수정할 수 있는 네이티브 PPTX임.
•
슬라이드 전체를 이미지 1장으로 붙이는 방식과 달리 문구·색상·위치를 PowerPoint에서 수정할 수 있음.
•
AI 생성 이미지와 사진은 이미지 개체이므로, 그림 내부의 모든 요소가 PowerPoint 도형으로 변환되는 것은 아님.
•
데이터가 연결된 PowerPoint 차트·표가 필요하면 관련 옵션과 지원 범위를 확인하기.
1-3. 전체 제작 과정
•
기본 제작 과정은 원고 분석 → 프로젝트 생성 → 전략 확인 → 이미지 준비 → SVG 슬라이드 작성 → 품질 검사 → PPTX 내보내기 순서임.
•
SVG는 슬라이드의 배치와 디자인을 표현하는 중간 파일이며, 자체 변환기로 PowerPoint 개체로 변환됨.
•
사용자는 제작 방향 확정·프리뷰 검토·수정 요청·최종 파일 확인을 담당함.
•
자동 검사를 통과해도 원고의 사실관계와 발표 목적에 맞는지는 사용자가 확인해야 함.
1-4. 양파고 버전의 변경 사항
•
hugohe3/ppt-master와 byungjunjang/slide-master를 기반으로 학교 업무에 맞게 커스터마이즈한 저장소임.
•
현재 README는 기본 이미지 모델을 Nano Banana 2.1, 이미지 수정용 프롬프트 재작성 모델을 Gemini 3.8 Flash로 설명함.
◦
모델명은 저장소 문서에 적힌 설정 기준이며, 실제 계정에서 해당 모델을 사용할 수 있는지는 별도로 확인해야 함.
◦
모델 오류가 발생하면 계정에서 사용할 수 있는 이미지 모델과 GEMINI_MODEL 설정 확인하기.
•
Codex 이미지 모델은 CODEX_IMAGE_MODEL 환경변수로 지정할 수 있도록 안내됨.
•
양파고 브랜드 색상 프리셋인 yangphago와 supabase 덱 템플릿이 추가됨.
•
API 키 설정용 .env.example 파일이 제공됨.
1-5. 학교 업무 활용 예시
•
회의 원고를 안건·현황·논의 사항 중심의 보고용 PPT로 구성하는 데 활용 가능함.
•
수업 자료를 개념 설명·사례·활동 안내 중심의 슬라이드로 구성하는 데 활용 가능함.
•
기존 학교 PPTX 양식에 새 내용을 채우거나, 문구와 순서는 유지하면서 배치만 개선하는 요청이 가능함.
•
이 활용 예시는 저장소의 사용 패턴을 학교 업무에 맞게 구성한 요청 예시이며, 실제 제작 결과를 검증한 사례는 아님.
2. 설치와 첫 번째 PPT 제작
2-1. 준비물
•
Python 3.10 이상과 저장소 내려받기용 Git이 필요함.
•
AI 에이전트는 Claude Code가 권장되며, Codex CLI와 ChatGPT 데스크탑 앱의 Codex도 안내됨.
•
Windows에서 Python을 설치할 때 Add python.exe to PATH 항목 선택하기.
•
Node.js는 Codex CLI 설치나 OfficeCLI 사용 시 필요할 수 있는 선택 준비물임.
•
PPTX의 최종 편집과 발표 확인에는 Microsoft PowerPoint 사용을 권장함.
2-2. 저장소와 의존성 설치
•
터미널 또는 PowerShell에서 아래 명령어를 순서대로 실행하기.
git clone https://github.com/roughkyo/pptx_Agent.git
cd pptx_Agent
pip install -r requirements.txt
python -m playwright install chromium
powershell
복사
•
requirements.txt는 제작·변환·검사에 사용하는 Python 패키지 목록임.
•
Playwright와 Chromium은 슬라이드 렌더링과 시각 검사에 사용됨.
•
Playwright를 설치하지 않으면 시각 검사 대신 정적 검사만 동작할 수 있음.
2-3. Pretendard 글꼴 설치
•
이 저장소의 덱은 Pretendard 글꼴 1개 가족을 사용하도록 구성됨.
•
.claude/skills/ppt-master/assets/fonts/Pretendard/ 폴더의 글꼴 파일을 선택해 설치하기.
•
PPTX에는 글꼴이 내장되지 않으므로 작업 PC와 발표 PC 모두에 Pretendard 설치하기.
•
다른 PC에서 글꼴 설치가 어려우면 발표용 PDF를 함께 준비하기.
2-4. AI 이미지 생성 설정
•
Gemini API 방식으로 이미지를 생성하려면 .env.example을 .env로 복사하기.
Copy-Item .env.example .env
powershell
복사
•
Google AI Studio에서 발급받은 API 키를 .env의 GEMINI_API_KEY 항목에 직접 입력하기.
•
키를 채팅창이나 노션 본문에 붙여 넣지 않고, 로컬 .env 파일에서만 관리하기.
•
파일 확장자가 .env.txt로 저장되지 않았는지 확인하기.
•
API 이미지 생성은 선택 기능이며, Gemini 키 없이 도형·아이콘 중심으로 제작하는 방식도 가능함.
•
보존된 원 프로젝트 문서에는 Codex CLI 로그인 방식의 이미지 생성도 안내되므로, Gemini 키 유무와 모든 이미지 생성 방식의 가능 여부를 구분해야 함.
2-5. 설치 확인과 선택 검증 도구
•
아래 명령어로 제작 환경 확인하기.
python .claude/skills/ppt-master/scripts/preflight.py
powershell
복사
•
오류가 발생하면 오류 메시지를 AI 에이전트에 제공해 필요한 패키지나 설정 확인하기.
•
내보낸 PPTX를 추가 검사하려면 README에 안내된 OfficeCLI 설치 명령어 사용하기.
npm install -g @officecli/officecli@1.0.135
powershell
복사
•
OfficeCLI는 선택 도구이며, 패키지 무결성·텍스트 넘침·렌더링 점검에 활용됨.
2-6. 원고 준비와 제작 요청
•
AI 에이전트에서 pptx_Agent 폴더 열기.
•
원고를 projects/ 아래에 저장하거나 채팅에 직접 입력하기.
•
요청문에 원고 경로·발표 목적·대상·장수·문체·강조할 내용을 함께 제시하기.
•
회의 자료 요청 예시임.
projects/회의자료/원고.md로 표지 포함 11장 회의용 PPT 만들어줘.
대상은 교직원이고, 문구는 개조식으로 작성해줘.
안건별 현황과 논의할 사항을 구분하고, 원고에 없는 수치는 추가하지 마.
text
복사
•
수업 자료 요청 예시임.
이 PDF로 고등학생 대상 AI 기초 수업용 PPT를 10장 내외로 만들어줘.
핵심 개념, 실제 사례, 확인 질문을 구분해줘.
원자료에 없는 설명을 추가하면 출처와 추가 내용 여부를 표시해줘.
text
복사
2-7. 디자인 확인과 결과물 열기
•
전략 확인 페이지에서 화면 비율·장수·색상·이미지 방식을 검토하고 확정하기.
•
라이브 프리뷰 주소인 http://127.0.0.1:5050에서 슬라이드 제작 과정 확인하기.
•
기본 확인 항목은 제목의 가독성·본문 분량·이미지 적절성·슬라이드 간 일관성임.
•
양파고 버전 README의 결과물 위치는 projects/<프로젝트>/exports/<제목>_ver1.pptx임.
•
실제 생성된 경로를 확인하고 PowerPoint에서 파일 열기.
3. 수정과 확장 기능 활용
3-1. 채팅과 주석을 활용한 수정
•
채팅에서는 수정할 슬라이드 번호·대상 요소·원하는 변경 사항을 구체적으로 제시하기.
•
수정 요청 예시는 “4장 본문 글자 크기를 키워줘”, “10장 논의 사항을 더 크게 표시해줘” 등임.
•
라이브 프리뷰에서는 요소를 클릭해 수정 의견을 주석으로 남길 수 있음.
•
주석을 제출한 뒤 채팅에 “주석 반영해줘”라고 요청하기.
•
수정 후에는 프리뷰뿐 아니라 다시 내보낸 PPTX에서도 결과 확인하기.
3-2. 라이브 프리뷰 직접 편집
•
Getting Started 문서에는 프리뷰에서 텍스트·색상·글꼴·크기를 수정하고 요소 위치를 이동하는 기능이 안내됨.
•
직접 편집한 내용은 Apply changes로 svg_output/에 반영되는 방식임.
•
프리뷰 편집 결과를 최종 PPTX에 포함하려면 변경 사항 저장 후 다시 내보내기.
•
AI에게 수정 방향을 전달할 때는 주석 방식, 배치를 직접 조정할 때는 직접 편집 방식 사용하기.
3-3. AI 이미지 수정과 버전 관리
•
표지나 마무리 이미지가 목적에 맞지 않으면 원하는 분위기·구도·색상·제외할 요소를 구체적으로 제시하기.
•
저장소 README는 피드백에 따라 프롬프트를 다시 작성하고 이미지를 재생성하는 흐름을 설명함.
•
이전 이미지 프롬프트는 image_prompts.json의 prompt_history에 남도록 안내됨.
•
수정 후 내보낸 PPTX는 _ver2.pptx, _ver3.pptx처럼 버전 번호가 증가함.
•
같은 프로젝트에서 동일한 제목을 사용하는 경우 가장 큰 버전 번호의 파일을 최신본으로 확인하기.
•
발표용 확정본은 파일명과 저장 위치를 별도로 확인해 이전 버전과 혼동하지 않도록 관리하기.
3-4. 기존 PPTX 활용과 템플릿 재사용
•
기존 PPTX에 내용만 채우는 방식과 기존 PPTX의 스타일로 새 덱을 만드는 방식은 서로 다름.
•
원본 양식 유지가 목적이면 “이 템플릿 PPTX의 디자인을 유지하고 새 내용으로 채워줘”라고 요청하기.
•
스타일을 반복해서 재사용하려면 create-template 흐름으로 템플릿을 먼저 생성하기.
•
재사용 템플릿 적용 시에는 템플릿 이름만 제시하지 않고 생성된 작업 폴더 경로를 함께 제공하기.
•
기존 자료의 문구와 순서 보존이 중요하면 아래와 같이 요청하기.
이 PPTX의 문구와 슬라이드 순서는 유지해줘.
내용을 요약하거나 삭제하지 말고, 글자 크기·간격·정렬·레이아웃만 개선해줘.
text
복사
3-5. 발표자 노트·애니메이션·나레이션
•
완성된 PPTX에 발표자 노트와 음성 나레이션을 추가하는 워크플로우가 안내됨.
•
페이지 전환과 요소별 등장 애니메이션은 PowerPoint 애니메이션 형식으로 내보낼 수 있음.
•
나레이션은 슬라이드별 발표자 노트를 바탕으로 음성을 생성하고 PPTX에 포함하는 방식임.
•
영상 제작은 나레이션이 포함된 PPTX를 PowerPoint에서 영상으로 내보내는 흐름으로 안내됨.
•
음성 서비스별 설정과 비용이 다를 수 있으므로 상세 가이드 확인하기.
•
다른 사람의 복제 음성을 사용할 때는 본인의 명시적 허락 받기.
•
다른 발표 프로그램에서는 애니메이션이 다르게 표시될 수 있으므로 실제 발표 환경에서 확인하기.
3-6. 학교 업무용 수정 요청 예시
•
회의 자료에서는 안건별 현황과 결정할 사항을 구분하도록 요청하기.
•
수업 자료에서는 개념 설명과 활동 안내를 별도 슬라이드로 나누도록 요청하기.
•
연수 발표에서는 발표자 노트에 설명을 보강하고 슬라이드 본문은 핵심 문장으로 제한하도록 요청하기.
•
최종 점검 요청 예시임.
주석을 반영해 새 버전으로 내보내줘.
문구 누락, 글자 넘침, 요소 겹침을 확인하고 PPTX 검증도 진행해줘.
자동 검사 결과와 내가 직접 확인해야 할 항목을 구분해 알려줘.
text
복사
Ⅳ. 품질 확인·문제 해결·안전한 사용
4-1. 자동 검사와 최종 확인
•
제작 과정에서 텍스트 겹침·캔버스 이탈·줄바꿈 등 배치 문제를 검사하도록 구성됨.
•
필요하면 페이지별 시각 검토와 OfficeCLI 기반 내보내기 검증을 요청할 수 있음.
•
자동 검사는 모든 사실 오류나 교육적 적절성을 보장하지 않으므로 원고와 결과물을 직접 비교하기.
•
날짜·수치·고유명사·인용문·출처·누락된 항목을 우선 확인하기.
•
PowerPoint에서 텍스트와 도형이 개별적으로 선택·수정되는지 확인하기.
•
발표 PC에서 글꼴·줄바꿈·이미지·애니메이션을 확인하고 필요하면 PDF도 함께 준비하기.
4-2. 자주 발생하는 문제와 대응
•
설치 오류가 발생하면 실행한 명령어와 오류 메시지를 함께 AI 에이전트에 제공하기.
•
미리보기 주소가 열리지 않으면 “미리보기 다시 열어줘”라고 요청하기.
•
API 키 오류가 발생하면 .env 파일명과 키 앞뒤 공백 확인하기.
•
이미지 모델 오류가 발생하면 .env의 GEMINI_MODEL 설정과 계정의 모델 사용 가능 여부 확인하기.
•
한글이 깨지면 PowerShell에서 아래 환경변수를 설정한 뒤 다시 실행하기.
$env:PYTHONIOENCODING='utf-8'
powershell
복사
•
배치 문제가 남으면 문제 슬라이드와 수정할 요소를 지정해 재작성하거나 프리뷰에서 직접 조정하기.
•
AI가 제작 절차를 생략하면 .claude/skills/ppt-master/SKILL.md를 다시 읽고 진행하도록 요청하기.
4-3. 개인정보·API 키·사용료 관리
•
학생 실명·연락처·학번 등 개인 식별 정보는 원고에서 제거한 뒤 제공하기.
•
학생 상담 내용이나 민감한 학교 내부 자료는 소속 기관의 외부 AI 사용 기준을 확인한 뒤 처리하기.
•
파일 생성과 변환은 로컬에서 진행되지만, AI가 분석하는 원고 내용은 사용하는 AI 서비스로 전송될 수 있음.
•
.env를 공개 저장소·공유 문서·메신저에 올리지 않고 API 키가 포함되지 않았는지 확인하기.
•
키가 노출되면 발급 서비스에서 기존 키를 폐기하고 새 키로 교체하기.
•
도구 자체는 무료·오픈소스이지만, AI 에이전트와 API 사용에는 요금이 발생할 수 있음.
•
덱 분량·이미지 생성·수정 횟수에 따라 비용이 달라질 수 있으므로 해당 서비스에서 사용량 확인하기.
•
AI 이미지의 부정확한 글자·로고·인물 표현과 사용 권한을 최종 확인하기.
4-4. 저장소 구조와 참고 문서
•
CLAUDE.md와 AGENTS.md는 Claude Code·Codex가 읽는 프로젝트 진입점임.
•
.claude/skills/ppt-master/에는 SKILL.md, references/, scripts/, workflows/, templates/ 등이 포함됨.
•
projects/는 프로젝트별 원고·중간 파일·결과물을 저장하는 작업 공간임.
•
docs/는 설치·사용·템플릿·나레이션·문제 해결 가이드를 제공하는 폴더임.
4-5. 라이선스와 저작권
•
저장소는 MIT 라이선스를 따르며, hugohe3/ppt-master와 byungjunjang/slide-master의 원 프로젝트 고지를 유지함.
•
번들 글꼴·아이콘은 각각의 라이선스를 따르므로 저장소 라이선스와 구분해 확인하기.
•
코드와 자산을 재배포할 때는 해당 라이선스의 저작권·허가 고지 유지 조건 확인하기.
•
문서 기준은 저장소와 README를 확인한 2026-10-09이며, 실제 모델 제공 여부와 제작 성공 여부를 별도로 시험한 문서는 아님.