| name | toon-slide |
| description | 인스타툰 이미지 생성 파이프라인. 콘텐츠 문서(콘티/에피소드 설계/아트 디렉션)를 입력받아 story-writer -> ref 탐색 -> pipeline-slide(검수+생성)까지 전체 워크플로우를 실행한다.
|
| allowed-tools | ["Agent(story-writer)","Agent(reference-explorer)","Bash(node --import tsx ${CLAUDE_SKILL_DIR}/scripts/*)","Read","Write","Glob"] |
| argument-hint | --episode N [--slide N] [--content-dir path] [--model model-name] |
toon-slide
인스타툰 이미지 생성 파이프라인 스킬.
콘텐츠 문서를 입력받아 프롬프트 JSON 생성 -> ref 탐색 -> 검수+이미지 생성까지 전체 워크플로우를 오케스트레이션한다.
인자
--episode N (필수): 생성할 에피소드 번호--slide N (선택): 특정 슬라이드만 생성 (미지정 시 전체)--content-dir path (선택): 콘텐츠 문서 루트 디렉토리 (기본: ./content)--model model-name (선택): 이미지 모델을 고정 지정. 미지정 시 슬라이드별 Gemini 자동 선택. gpt-image-2 지정 가능
모델 자동 선택 전략
--model 미지정 시, 각 슬라이드의 textOverlay 유무에 따라 모델이 자동 선택된다:
| 조건 | 선택 모델 | 이유 |
|---|
textOverlay 또는 episodeTitle 있음 | gemini-3-pro-image-preview (Pro) | 한글 텍스트 렌더링 정확도 우수 |
textOverlay 없음 | gemini-3.1-flash-image-preview (Flash) | 빠르고 저렴 |
| E단계 에셋 생성 | Flash 권장 | 참고용 에셋, 텍스트 불필요 |
--model gpt-image-2를 지정하면 자동 선택을 무시하고 OpenAI Image API로 생성한다.
사전 조건
- Gemini 모델 사용 시
GEMINI_API_KEY 환경변수 설정
- OpenAI 모델(
gpt-image-2) 사용 시 OPENAI_API_KEY 환경변수 설정
{content-dir}/ 아래에 콘텐츠 문서가 존재해야 함- 프로젝트 루트에
zod, @google/genai 패키지가 설치된 상태 (npm install)
- 사전 조건이 충족되지 않으면 스킬 실행 전에 사용자에게 안내하고, 필요한 패키지를 설치할지 확인한다
필요한 콘텐츠 문서
| 파일 | 용도 | 필수 |
|---|
{content-dir}/conti/EP{N}.md | 슬라이드별 화면/텍스트/연출 | 필수 |
{content-dir}/episode-design/EP{N}.md | 에피소드 감정/구조/장면 설계 | 필수 |
{content-dir}/visual/art-direction.md | 아트 디렉션 (스타일/색감/금지 요소) | 필수 |
{content-dir}/visual/character-sheet-detailed.md | 상세 캐릭터 시트 (외형/감정 표현) | 필수 |
{content-dir}/visual/references/ | 레퍼런스 이미지 디렉토리 | 권장 |
출력 구조
output/
prompts/EP{N}_prompts.json # 1단계 출력
assets/EP{N}/ # E단계 에셋 (필요시)
EP{N}/ # 최종 이미지
EP{N}_S{NN}_{slug}.png
EP{N}_S{NN}_{slug}.meta.json
variables/ # 개선 루프 변형본
워크플로우
1단계: story-writer -> 프롬프트 JSON 생성
story-writer 에이전트를 호출하여 프롬프트 JSON을 생성한다.
호출:
Agent(story-writer): "EP{N} 이미지 프롬프트를 생성해줘. content-dir: {content-dir}"
확인사항:
- 출력 파일:
output/prompts/EP{N}_prompts.json
episodeTitle 필드는 슬라이드 1(커버)에만 포함toneReference 필드가 존재하고 실제 파일을 가리키는지 확인- 조연 등장 EP이면
supportingCharacterPrefix와 hasSupportingCharacter 확인
2단계: 슬라이드별 반복 (A -> B -> pipeline-slide)
각 슬라이드에 대해 아래를 순서대로 실행한다.
A. 요소 정의 (오케스트레이터)
프롬프트 JSON과 콘티를 읽고, 해당 슬라이드에 필요한 요소를 정의한다.
읽을 파일:
output/prompts/EP{N}_prompts.json - 해당 슬라이드의 prompt, colorMood{content-dir}/conti/EP{N}.md - 해당 슬라이드의 연출 포인트
정의 항목:
- 배경: 공간, 시간대, 분위기
- 인물(포즈/표정): 주인공의 자세, 시선, 감정 표현
- 사물(소품/UI): 장면에 등장하는 오브젝트
B. ref 탐색 (reference-explorer 에이전트)
A에서 정의한 요소를 reference-explorer 에이전트에 전달한다.
호출:
Agent(reference-explorer):
"에피소드: EP{N}, 슬라이드: {S}
content-dir: {content-dir}
요소 정의:
- 배경: {배경 설명}
- 인물: {인물 설명}
- 사물: {사물 설명}
프롬프트: {prompt 텍스트}
colorMood: {colorMood}"
에이전트가 누락 요소를 보고하면:
- 누락된 요소에 대해 에셋 생성이 필요 → 아래 E단계 실행 후 ref 목록에 추가
E. 에셋 생성 (ref가 부족할 때만)
reference-explorer가 누락으로 보고한 요소만 새로 생성한다.
에셋용 프롬프트 JSON 작성:
{
"episode": {N},
"title": "에셋 설명",
"stylePrefix": "(art-direction.md에서 추출)",
"characterPrefix": "",
"prompts": [{ "slideNumber": 1, "prompt": "...", "textOverlay": "", "colorMood": "..." }]
}
호출:
node --import tsx ${CLAUDE_SKILL_DIR}/scripts/generate.ts \
--prompt {asset_prompt.json} \
--slide 1 \
--ratio 4:5 \
--output-dir output/assets/EP{N} \
--content-dir {content-dir}
캐릭터 에셋 규칙:
- 캐릭터 포즈 에셋 생성 시 반드시 기존 캐릭터 시트를
--ref로 포함
- 기존 캐릭터 ref 탐색:
Glob: {content-dir}/visual/references/character/**/*
C+D+F. pipeline-slide 실행 (검수 + 생성)
B(+E)에서 확보한 ref를 pipeline-slide.ts에 전달한다.
pipeline-slide.ts가 C(검수) → D(선정) → F(생성) + dimension 검증을 코드로 강제한다.
호출:
node --import tsx ${CLAUDE_SKILL_DIR}/scripts/pipeline-slide.ts \
--prompt output/prompts/EP{N}_prompts.json \
--slide {S} \
--ratio 4:5 \
--ref {bg_ref} {char_ref} [obj_ref] \
--concept "{슬라이드 컨셉}" \
--content-dir {content-dir} \
[--model {model}]
결과 처리:
| exit code | 의미 | 다음 단계 |
|---|
| 0 | 성공 | 다음 슬라이드로 |
| 1 | 생성 실패 | 에러 확인 후 재시도 |
| 2 | ref 검수 실패 (INSPECT FAIL) | B로 돌아가 다른 ref 탐색, 또는 E에서 에셋 생성 (최대 2회) |
exit code 2일 때 INSPECT_RESULT JSON이 출력된다.
issues와 suggestions를 참고하여 다른 ref를 찾거나 에셋을 생성- 재시도는 최대 2회까지
개선 루프 (검수 후)
슬라이드 생성 완료 후, 생성된 이미지를 검수하고 필요시 개선한다.
검수 방법
inspect.ts로 생성된 이미지를 검수:
node --import tsx ${CLAUDE_SKILL_DIR}/scripts/inspect.ts \
--refs output/EP{N}/EP{N}_S{NN}_{slug}.png \
--concept "{슬라이드 컨셉}" \
--prompt "{원본 프롬프트}" \
--art-direction {content-dir}/visual/art-direction.md
개선 처리
- score 90+ : 루프 종료, 다음 슬라이드로
- score < 90 : 개선본을
output/EP{N}/revisions/에 생성
- 원본을 직접 덮어쓰지 않는다
- 최대 3회 개선 시도 후 사용자에게 판단 위임
재생성 규칙 (원본 보존)
생성된 슬라이드에 대해 재생성/개선을 요청할 때, 원본은 항상 보존한다.
디렉토리 구조
output/EP{N}/
EP{N}_S01_cover.png # 원본 (덮어쓰지 않음)
EP{N}_S01_cover.meta.json
...
revisions/ # 재생성/개선본 폴더
v1/
EP{N}_S03_scene3.png # 1차 개선본
EP{N}_S03_scene3.meta.json
EP{N}_S03_scene3.prompt.json # 개선에 사용한 프롬프트
v2/
EP{N}_S03_scene3.png # 2차 개선본
...
규칙
- 원본 덮어쓰기 금지:
output/EP{N}/EP{N}_S{NN}_{slug}.png는 최초 생성본을 유지
- 개선본 위치:
output/EP{N}/revisions/v{N}/에 버전별로 저장
- 프롬프트 보존: 개선에 사용한 수정 프롬프트를
.prompt.json으로 함께 저장
- 채택 시 교체: 사용자가 개선본을 확인하고 채택을 명시하면, 그때 원본 위치로 복사
- 버전 넘버링:
v1, v2, v3 순서로 증가 (기존 revisions 폴더 확인 후 다음 번호 부여)
prompt.json 형식
{
"originalSlide": 3,
"revisionVersion": 1,
"changeReason": "배경 톤이 너무 밝아 감정선과 불일치",
"modifiedPrompt": "...(수정된 프롬프트 전문)",
"modifiedRefs": ["ref1.png", "ref2.png"],
"inspectScore": {
"before": 72,
"after": 91
}
}
스크립트 경로
모든 스크립트는 ${CLAUDE_SKILL_DIR}/scripts/ 아래에 위치한다:
| 스크립트 | 용도 |
|---|
pipeline-slide.ts | 슬라이드별 파이프라인 (C검수 → D선정 → F생성 + dimension 검증) |
generate.ts | Gemini API로 이미지 생성 (pipeline-slide가 내부 호출) |
inspect.ts | ref/이미지 적합성 검증 (pipeline-slide가 내부 호출) |
에이전트
| 에이전트 | 용도 | 모델 |
|---|
story-writer | 프롬프트 JSON 생성 | sonnet |
reference-explorer | ref 이미지 탐색/추천 | haiku |
EP간 스타일 일관성 규칙
EP2 이상을 생성할 때는 이전 EP에서 생성된 이미지를 스타일 ref로 활용하여 시리즈 일관성을 유지한다.
일관성 체크리스트 (EP2+ 생성 전 확인):
주의사항
- 에셋 생성은 ref가 부족할 때만 실행 (불필요한 에셋 생성 방지)
- 같은 공간은 EP 간에 동일한 ref를 재활용하여 배경 일관성 유지
- 이전 EP의 생성된 이미지는 스타일 일관성이 검증된 ref이므로 적극 활용
