Document Illustrator Skill
AI 기반 문서 분석 및 일러스트레이션 생성 도구입니다. 특정 형식에 의존하지 않고 문서 내용을 자동으로 이해하여 전문적인 이미지를 생성합니다.
🎯 핵심 특징
- ✨ AI 스마트 요약: 문서 내용을 자동으로 이해하고 핵심 주제를 지능적으로 추출합니다.
- 🎨 형식 무관: 마크다운, 일반 텍스트, PDF 등 모든 형식의 문서를 지원합니다.
- 📐 유연한 비율: 16:9(가로)와 3:4(세로) 비율을 지원합니다.
- 🖼️ 표지 이미지 선택 가능: 문서 전체를 요약하는 표지 이미지를 생성할 수 있습니다.
- 🎭 세 가지 스타일: 그래디언트 글래스 카드, 티켓 스타일, 벡터 일러스트레이션.
🚀 사용 방법
Codex에 직접 지시하기
이 문서에 일러스트레이션을 생성해 줘: /path/to/document.md
또는:
이 글에 일러스트레이션을 몇 장 만들고 싶어
📝 전체 워크플로우
1단계: Codex가 문서를 읽고 이해합니다
일러스트레이션 생성을 요청하면 Codex는 다음을 수행합니다:
- Read 도구를 사용하여 전체 문서를 읽습니다.
- AI가 문서 내용과 구조를 분석합니다.
- 핵심 주제와 요점을 식별합니다.
문서 형식에 대해 걱정하지 마세요:
- ✅ 표준 마크다운 (##, ###)
- ✅ 구분선 형식 (======, ------)
- ✅ 일반 텍스트 단락
- ✅ 기타 모든 형식
2단계: 설정 옵션 (3가지 질문)
Codex가 사용자의 선호도를 묻습니다:
질문 1: 이미지 비율
이미지 비율을 선택하세요:
1. 16:9 (가로) - 프레젠테이션, 슬라이드, 가로 화면에 적합
2. 3:4 (세로) - 소셜 미디어, 모바일, 포스터에 적합
선택 (1/2):
질문 2: 표지 이미지
표지 이미지를 생성하시겠습니까?
표지 이미지는 문서의 모든 핵심 정보를 요약하여 일러스트레이션 시리즈의 가이드 역할을 합니다.
1. 예 - 표지 이미지 + 콘텐츠 이미지 생성
2. 아니요 - 콘텐츠 이미지만 생성
선택 (1/2):
질문 3: 콘텐츠 이미지 개수
몇 장의 콘텐츠 이미지를 생성하시겠습니까?
권장 범위: 3-10장
문서 내용에 따라 6장을 권장합니다.
숫자를 입력하세요:
3단계: Codex가 내용을 요약하여 보여줍니다
지정한 개수에 따라 Codex가 문서를 지능적으로 요약한 후 사용자에게 확인을 요청합니다:
📋 내용 요약 완료
📄 표지 이미지 내용: (표지 생성 선택 시)
"AI 프로그래밍 도구 개념 진화: Rules에서 Skills까지"
- 핵심 개념: 정적 컨텍스트 vs 동적 컨텍스트
- 진화 경로: Rules → Commands → MCP → Modes → Skills
- 모범 사례: 두 가지 핵심 도구로 단순화
📚 콘텐츠 이미지 (총 6장):
1. Rules의 탄생과 진화
포함: 초기 모델 환각 문제, rules 파일의 역할, 정적 컨텍스트 개념
2. Commands와 워크플로우 패키징
포함: 고정 워크플로우의 등장, slash command, 팀 공유
3. MCP Servers가 동적 기능 제공
포함: 서드파티 도구 통합, OAuth 인증, 컨텍스트 팽창 문제
4. Modes와 Subagents의 등장
포함: 페르소나 프롬프트, 시스템 프롬프트 수정, 안정성 설계, Hooks 결정성
5. Skills가 동적 컨텍스트 통합
포함: Skills 개념, 동적 로딩, 프로그래밍 도구 최적화
6. 모범 사례와 미래 전망
포함: Rules 사용 제안, Skills 탐구, 핵심 개념 요약
✓ 모든 내용이 포함되었습니다. 누락 없음
일러스트레이션 생성을 시작할까요? (Y/N)
핵심 보장 사항:
- ✅ 내용 완전성: 모든 중요한 정보가 각 이미지에 포함됩니다.
- ✅ 논리적 명확성: 콘텐츠의 자연스러운 논리 흐름에 따라 분할됩니다.
- ✅ 사용자 제어 가능: 요약 결과를 표시하고 사용자 확인을 받습니다.
4단계: 일러스트레이션 생성
확인 후 Codex가 Python 스크립트를 호출하여 이미지를 생성합니다:
🖼️ 일러스트레이션 생성 시작...
표지 이미지 생성 중...
✓ 저장됨: /path/to/document/images/cover.png
1/6번째 이미지 생성 중...
제목: Rules의 탄생과 진화
✓ 저장됨: /path/to/document/images/illustration-01.png
2/6번째 이미지 생성 중...
제목: Commands와 워크플로우 패키징
✓ 저장됨: /path/to/document/images/illustration-02.png
...
✨ 완료! 총 7장의 일러스트레이션 생성됨 (표지 1장 + 콘텐츠 6장)
5단계: 결과 출력
출력 위치: 문서가 있는 디렉토리의 images/ 폴더
/path/to/your/document/
└── images/
├── cover.png # 표지 이미지 (생성 선택 시)
├── illustration-01.png # 1번째 콘텐츠 이미지
├── illustration-02.png # 2번째 콘텐츠 이미지
├── illustration-03.png
├── illustration-04.png
├── illustration-05.png
└── illustration-06.png
🎨 세 가지 스타일 설명
1. 그래디언트 글래스 카드 스타일 (gradient-glass)
특징:
- Apple Keynote 스타일의 미니멀리즘
- 글라스모피즘(Glassmorphism) 디자인
- 깊고 어두운 보이드 블랙 또는 순수한 세라믹 화이트 베이스
- 흐르는 오로라 그라데이션 색상
- 3D 유리 오브제와 발광 효과
적용 시나리오:
- 기술 제품 소개
- 데이터 분석 보고서
- 미래 트렌드 전망
- 제품 기능 데모
2. 티켓 스타일 (ticket)
특징:
- 디지털 미니멀 티켓 디자인
- 높은 대비의 흑백 색상
- 탑승권, 입장권과 유사한 구조
- 정확한 기하학적 분할
- 한중 혼용, 다방향 텍스트 레이아웃
적용 시나리오:
- 인포그래픽
- 통계 데이터 표시
- 타임라인 및 순서도
- 요점 요약
3. 벡터 일러스트레이션 스타일 (vector-illustration)
특징:
- 플랫 디자인 벡터 일러스트레이션
- 균일한 두께의 검은색 외곽선
- 레트로 파스텔 색상
- 기하학적 처리
- 가로 파노라마 구성
적용 시나리오:
- 스토리텔링
- 개념 설명
- 교육 콘텐츠
- 브랜드 홍보
💡 사용 예시
예시 1: 전체 프로세스
사용자: ~/blog/ai-tools.md 문서에 일러스트레이션을 생성해 줘, 티켓 스타일로
Codex: 네, 먼저 이 문서를 읽어보겠습니다...
[문서 읽기, 내용 분석]
문서 길이는 약 3000자이며, AI 도구 진화에 관한 내용입니다.
이미지 비율을 선택하세요:
1. 16:9 (가로)
2. 3:4 (세로)
사용자: 1
Codex: 표지 이미지를 생성하시겠습니까?
1. 예
2. 아니요
사용자: 예
Codex: 몇 장의 콘텐츠 이미지를 생성하시겠습니까?
권장 범위: 3-10장
문서 내용에 따라 5장을 권장합니다.
사용자: 5
Codex: [요약된 5가지 주제 표시]
일러스트레이션 생성을 시작할까요?
사용자: Y
Codex: [Python 스크립트를 호출하여 6장의 이미지 생성]
✨ 완료! 일러스트레이션이 ~/blog/images/에 저장되었습니다.
예시 2: 일반 텍스트 문서
사용자: 이 일반 텍스트 노트에 일러스트레이션을 생성해 줘
Codex: [제목이 없어도 노트를 읽고 내용을 이해]
[3가지 핵심 주제를 지능적으로 식별]
[설정 확인, 요약 표시, 이미지 생성]
예시 3: 사용자 지정 개수
사용자: 8장의 그림을 원해, 세로로, 표지는 없이
Codex: 네, 16:9 세로, 표지 없음, 8장의 콘텐츠 이미지.
[문서를 8가지 주제로 요약]
[요약 결과 표시, 사용자 확인 후 생성]
🔧 기술 세부 사항
이미지 사양
다음 비율과 해상도는 Gemini에 적용됩니다. Nebula image2-4k는 16:9, 3840x2160만 지원합니다. 사용자가 Nebula를 선택하면 바로 4K를 사용합니다. 사용자가 2K 또는 세로 이미지를 요청할 경우 먼저 제한 사항을 설명하고 지원되는 방안을 결정합니다.
| 비율 | 해상도 | 적용 시나리오 |
|---|---|---|
| 16:9 | 2560x1440 (2K) | 프레젠테이션, 가로 화면 |
| 3:4 | 1920x2560 | 소셜 미디어, 세로 화면 |
선택 가능한 4K 해상도:
- 16:9 → 3840x2160
- 3:4 → 2880x3840
API 호출
- Gemini 모델:
gemini-3-pro-image-preview(스크립트 현재 기본값) - Nebula 모델:
gpt-image-2-4k, image2-4k 그룹 토큰 사용 - 비용: 이미지 1장 = API 호출 1회
- 속도: 백엔드 부하에 따라 다름. Nebula 4K 요청 타임아웃은 1800초
백엔드 선택 및 Nebula 호출
nanobanana 그룹
사용자가 nanobanana를 지정하면 두 스크립트 모두 --provider nanobanana를 전달합니다.
통일된 .env에서 전용 NEBULA_NANOBANANA_API_KEY (nanobanana 그룹 토큰)를 사용하며,
image2-4k의 키를 재사용하지 않습니다. NEBULA_NANOBANANA_MODEL의 기본값은 gemini-3.1-flash-image이며,
토큰이 지원하는 다른 모델을 지정할 수 있습니다. ILLUSTRATOR_IMAGE_PROVIDER=nanobanana로 기본값을 설정할 수 있습니다.
단일 이미지, 배치 모두 16:9, 3:4를 지원합니다. 1K, 2K, 4K 요청 가능하며, 기본값은 2K입니다.
구체적인 지원 값과 실제 픽셀은 선택한 모델에 따라 결정되며, image2-4k의 4K 가로 이미지 제한이 적용되지 않습니다.
통일된 .env에서 ILLUSTRATOR_SINGLE_RATIO로 단일 이미지 기본 비율을,
ILLUSTRATOR_BATCH_RATIO로 배치 기본 비율을,
ILLUSTRATOR_RESOLUTION으로 기본 요청 해상도를 설정합니다.
두 진입점 모두 --ratio, --resolution을 통해 설정을 덮어쓸 수 있습니다.
설정하지 않거나 값이 비어 있으면 비율은 16:9,
해상도는 백엔드 기본값(Gemini/nanobanana는 2K, image2-4k는 4K)을 사용합니다.
이러한 설정은 모든 백엔드에 적용됩니다. 백엔드 제한과 충돌하는 경우 요청 전에 오류가 발생하므로,
설정을 조정하거나 명시적으로 덮어써야 합니다.
python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "주제" --content "이미지 내용" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py article.md --provider nanobanana --style ticket --level h2 --resolution 2K
Gemini 네이티브 POST /v1beta/models/{model}:generateContent를 호출하여 inlineData에서
이미지를 디코딩하고 검증하며, 전체 Base64 응답을 지속적으로 저장하지 않습니다. Google SDK가 필요하지 않습니다.
현재 연동은 텍스트-이미지 생성만 지원합니다. 타임아웃 시 유료 작업을 자동으로 재전송하지 않습니다.
자세한 내용은 README.md 및
공식 API 문서를 참조하세요.
기존 image2-4k 그룹
두 스크립트 모두 --provider gemini|nebula를 지원합니다. 지정하지 않으면 ILLUSTRATOR_IMAGE_PROVIDER를 읽으며,
설정되지 않은 경우 Gemini를 사용합니다. 사용자가 명시적으로 Nebula를 지정하면 --provider nebula를 전달합니다. 다른 서비스를 사용하지 마십시오.
통일된 경로 ~/.agents/skills/document-illustrator/.env에 NEBULA_API_KEY를 설정하거나 동일한 이름의 환경 변수를 사용합니다. 토큰은 image2-4k 그룹에 속해야 합니다.
Nebula는 Gemini 키나 Google SDK가 필요하지 않지만, Pillow와 python-dotenv는 필요합니다.
python -X utf8 scripts/generate_single_image.py --provider nebula --title "주제" --content "확인된 이미지 내용" --style-file styles/ticket.md --output output/image-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py article.md --provider nebula --style ticket --level h2 --resolution 4K
스크립트는 POST https://img-api.apinebula.ai/v1/images/generations를 호출하며,
고정적으로 gpt-image-2-4k, 3840x2160, quality=high, response_format=url을 사용합니다.
URL을 우선적으로 읽고 Base64도 호환합니다. 저장 전에 실제 픽셀을 검증하고, 서버 측 JPEG를 로컬 확장자에 해당하는 형식으로 변환합니다.
API 응답은 <이미지 파일 이름>.response.json으로 저장되며, 다운로드 실패 시 임시 링크를 재사용하여 다운로드를 재개합니다.
POST 타임아웃 후 작업 상태를 알 수 없으므로 자동으로 재전송하지 않습니다. 먼저 서버 측 상태를 확인하여 중복 청구를 방지하십시오.
HTTP 403 또는 연결이 설정되지 않은 경우 http://127.0.0.1:81 프록시를 시도합니다.
현재 텍스트-이미지 생성만 연동되어 있습니다. 참조 이미지 편집은 구현되지 않았습니다.
전체 설정 설명과 오프라인 테스트 명령은 README.md를 참조하고, API 매개변수는 공식 문서를 기준으로 합니다.
환경 요구 사항
필수:
pip install google-genai pillow python-dotenv
API 키:
- Codex, Claude 등 모든 Agent는 통일적으로
~/.agents/skills/document-illustrator/.env를 읽습니다. - Windows는
%USERPROFILE%\.agents\skills\document-illustrator\.env에 해당합니다. - 해당 파일만 로드하며, 그 값이 동일한 이름의 환경 변수를 덮어씁니다. 파일이 없으면 기존 환경 변수만 사용하고 다른 위치를 검색하지 않습니다.
- Gemini는
GEMINI_API_KEY, Nebula는NEBULA_API_KEY를 사용합니다. - nanobanana 그룹은
NEBULA_NANOBANANA_API_KEY를 사용합니다. 모델 구성은 위 그룹 설명을 참조하세요.
📊 내용 요약 원칙
Claude는 내용을 요약할 때 다음 원칙을 따릅니다:
1. 완전성 우선
- ✅ 모든 중요한 정보가 포함됩니다.
- ✅ 핵심 개념이 누락되지 않습니다.
- ✅ 원문의 핵심 관점이 유지됩니다.
2. 논리적 명확성
- 콘텐츠의 자연스러운 논리 흐름에 따라 분할됩니다.
- 관련 내용은 함께 그룹화됩니다.
- 스토리텔링의 일관성이 유지됩니다.
3. 균형 잡힌 분배
- 각 이미지는 비슷한 양의 정보를 포함합니다.
- 특정 이미지가 너무 빽빽하거나 비어 있지 않도록 합니다.
- 콘텐츠 중요도에 따라 조정합니다.
4. 사용자 제어 가능
- 요약 결과를 사용자에게 표시하여 확인을 받습니다.
- 사용자는 조정을 요청할 수 있습니다.
- 확인 후에 생성이 시작됩니다.
🐛 문제 해결
문제 1: API 키 오류
오류 메시지:
Error: Invalid API key
해결 방법:
.env파일에서 해당 백엔드의GEMINI_API_KEY또는NEBULA_API_KEY를 확인하세요. Nebula의 경우 토큰 그룹도 확인하세요.- API 키가 유효하고 만료되지 않았는지 확인하세요.
- 새 키 받기: https://makersuite.google.com/app/apikey
문제 2: 내용 요약이 만족스럽지 않은 경우
문제: 요약된 주제가 기대와 다릅니다.
해결 방법:
- 요약 표시 단계에서 codex에게 원하는 바를 알려주세요.
- codex가 다시 요약하여 조정합니다.
- 만족한 후에 생성을 시작하세요.
문제 3: 이미지 생성 실패
가능한 원인:
- 네트워크 연결 문제
- API 할당량 소진
- 콘텐츠가 너무 길어 제한 초과
해결 방법:
- 네트워크 연결을 확인하세요.
- API 할당량을 확인하세요.
- 이미지 개수를 늘려보세요 (콘텐츠 분산).
💰 비용 추정
| 이미지 개수 | API 호출 횟수 | 예상 비용 |
|---|---|---|
| 표지 없음 + 3장 | 3회 | 낮음 |
| 표지 있음 + 5장 | 6회 | 중간 |
| 표지 있음 + 10장 | 11회 | 높음 |
권장 사항:
- 짧은 문서 (<1000자): 3-5장
- 중간 문서 (1000-3000자): 5-7장
- 긴 문서 (>3000자): 8-10장
📚 모범 사례
1. 이미지 개수를 합리적으로 선택하세요
너무 적은 경우:
- 각 이미지의 정보량이 너무 많습니다.
- 이해하고 기억하기 어렵습니다.
너무 많은 경우:
- 콘텐츠가 분산됩니다.
- 비용과 생성 시간이 증가합니다.
권장 사항:
- 문서 길이에 따라 선택하세요.
- 각 이미지는 1-2개의 핵심 포인트를 다루도록 하세요.
2. 용도에 따라 비율을 선택하세요
16:9 적합:
- PPT 프레젠테이션
- 웹사이트 배너
- 비디오 커버
- 블로그 이미지 (데스크톱)
3:4 적합:
- 소셜 미디어 (Instagram, Xiaohongshu)
- 모바일 기사
- 포스터 디자인
- 세로 비디오
3. 표지 이미지 사용
표지 이미지 생성 권장 시나리오:
- 시리즈 기사 (통일된 가이드 역할)
- 소셜 공유 (미리보기 이미지 역할)
- 문서 첫 페이지 (전체 요약)
생성하지 않아도 되는 경우:
- 내부 용도로만 사용할 때
- 이미지 수가 이미 충분할 때
- 비용을 절감하고 싶을 때
4. 스타일 선택 권장 사항
기술 문서 → 그래디언트 글래스 카드 스타일 데이터 보고서 → 티켓 스타일 튜토리얼/스토리 → 벡터 일러스트레이션 스타일 제품 소개 → 그래디언트 글래스 카드 스타일
🔄 작동 원리
기존 방식 (폐기됨)
[코드] 문서 읽기 → ## ### 제목 식별 → 기계적 분할
↓
특정 형식에 의존
내용 누락 가능성
지능적이지 않음
새 방식 (현재 구현)
[Claude] 문서 읽기 → AI 내용 이해 → 지능적 주제 요약
↓
형식 무관
내용 완전
사용자 제어 가능
핵심 차이점:
- ❌ 기존 방식: 코드 구문 분석에 의존, 표준 형식만 처리 가능
- ✅ 새 방식: AI가 내용을 이해, 모든 형식 처리 가능
🎯 다른 도구와의 비교
| 기능 | Document Illustrator | 기존 PPT 도구 | AI 이미지 생성기 |
|---|---|---|---|
| 문서 내용 이해 | ✅ AI 스마트 이해 | ❌ 수동 필요 | ❌ 수동 입력 필요 |
| 형식 의존성 | ✅ 형식 무관 | ❌ 특정 형식 의존 | ✅ 의존 없음 |
| 내용 완전성 | ✅ 자동 검증 | ⚠️ 수동 확인 | ❌ 보장 불가 |
| 일괄 생성 | ✅ 한 번에 여러 장 생성 | ❌ 한 장씩 제작 | ⚠️ 여러 번 입력 필요 |
| 스타일 일관성 | ✅ 자동 유지 | ⚠️ 수동 조정 | ⚠️ 반복 프롬프트 필요 |
📞 도움말
질문이나 제안 사항이 있으면:
- codex에서 직접 문의하세요.
- Skill 디렉토리를 확인하세요:
~/.agents/skills/document-illustrator
AI가 문서를 이해하고 요약하여 전문적인 일러스트레이션을 생성하도록 하세요! ✨