jiangmuran/claude-image

Claude Code, Codex 등의 에이전트(agent)가 GPT Image 2의 drop-in skill 패키지를 진정으로 잘 활용할 수 있도록 가르칩니다. Claude Code, Codex 및 기타 에이전트가 GPT Image 2를 실제로 사용하도록 가르치는 drop-in skill입니다.

이것을 Claude Code나 Codex에 집어넣으면, 당신의 에이전트는 "이것은 curl 명령입니다, 행운을 빕니다" 수준에서 진화하여, 한 번에 pitch deck 슬라이드, 중국어 포스터, 픽셀 타일, 실사 제품 이미지, 외과 수술 수준의 이미지 수정 결과물을 만들어낼 수 있습니다.

GPT Image 2는 2026년 4월에 출시되었습니다. 이 세대는 분수령입니다. 긴 지시형 프롬프트(prompt)가 더 이상 세부 사항을 놓치지 않으며, 텍스트 렌더링이 마침내 정확해졌고(중국어, 일본어, 한국어 모두 지원), 사용자 정의 해상도는 최대 3840px까지 지원하며, 편집 엔드포인트(endpoint)는 change ONLY X / preserve Y exactly 모드를 사용하여 정밀한 국소 수정을 수행합니다.

하지만 문제가 있습니다. 2026년 4월 이전에 훈련된 에이전트는 아무것도 모릅니다. 그들은 기존 방식대로 프롬프트를 작성합니다—"4K, ultra detailed, masterpiece, trending on artstation"—이러한 단어들은 GPT Image 2에서 무시되거나 오히려 방해가 됩니다. 그들은 파일을 저장하지 않고 curl 명령에 매달립니다. 이미지를 생성한 후에는 스스로 확인하지 않고 사용자에게 "이게 맞나요?"라고 묻습니다.

이 skill이 이 모든 문제를 해결합니다.

gpt-image-2/
├── SKILL.md # 진입점. Claude가 자동으로 로드합니다.
├── README.md # 당신이 보고 있는 이 파일입니다.
...

이것을 단순한 장식품이 아닌 실제로 작동하게 만드는 세 가지 설계:

• 발견 가능한 설명 (discoverable description). frontmatter에 "포스터", "아이콘", "ppt 소재", "이미지 수정", "draw me", "make an image" 등 모든 트리거 단어를 나열했습니다. 따라서 에이전트의 skill 선택기가 이미지 요청을 받았을 때, 다시 돌아가서 직접 curl을 조합하는 대신 실제로 트리거됩니다.
• 하나의 CLI, 네 가지 능력. 생성(Generate) / 편집(Edit) / 국소 재그리기(Inpainting) / 병렬 배치 처리(Parallel batch processing)가 모두 하나의 스크립트 하위 명령어로 구성됩니다. 인증, 재시도, b64 vs URL, multipart, 파일 I/O, 병렬 배치 처리 등이 모두 처리되어 있습니다. 에이전트가 직접 구현하면 특정 항목에서 오류가 발생할 가능성이 높습니다.
• 워크플로우에 포함된 시각적 자가 검증 (visual self-verification). Skill은 Claude에게 결과를 사용자에게 전달하기 전에 생성된 PNG를 직접 Read하여 프롬프트와 대조하며 확인하도록 명시적으로 지시합니다. 더 이상 "이미지를 드렸으니 맞는지 확인해 보세요"라는 상황은 발생하지 않습니다.

git clone https://github.com/jiangmuran/claude-image.git ~/.claude/skills/gpt-image-2 \
&& bash ~/.claude/skills/gpt-image-2/install.sh

설치 스크립트는 API key를 요구하며, 이를 ~/.zshrc에 기록하고 선택적으로 스모크 테스트(smoke test)를 실행할 수 있습니다.

설치 후 다음 이미지 요청이 있으면 Claude가 자동으로 skill을 발견합니다. 재시작이나 등록이 필요 없습니다.

git clone https://github.com/jiangmuran/claude-image.git ~/.agents/skills/gpt-image-2 \
&& bash ~/.agents/skills/gpt-image-2/install.sh

동일한 skill, 동일한 스크립트, 동일한 환경 변수 세트입니다.

git clone https://github.com/jiangmuran/claude-image.git
cd gpt-image-2
echo 'export OPENAI_IMAGE_API_KEY="sk-..."' >> ~/.zshrc
...

두 개의 환경 변수만 있으면 됩니다. 설정은 이것이 전부입니다.

변수	필수 여부	기본값
OPENAI_IMAGE_API_KEY	예	—
OPENAI_IMAGE_BASE_URL	아니요	https://jmrai.net/v1

이미지 전용 두 변수를 설정하지 않으면 OPENAI_API_KEY / OPENAI_BASE_URL로 폴백(fallback)됩니다. 이미 동일한 키를 사용하여 chat completions를 실행 중이라면 매우 편리합니다.

**자체 구축한 Image 2 역방향 프록시(reverse proxy) API도 이 skill을 네이티브로 지원합니다 >_< ** https://order.jmrai.net

Key를 커밋하지 마세요. .gitignore에 이미 .env가 제외되어 있습니다.

.env.example

단지 템플릿일 뿐입니다.

전체 목록이 아닙니다 (전체 템플릿은 references/use-cases.md를 참조하세요):

Pitch-deck 슬라이드— "슬라이드 한 장을 그린 삽화"가 아니라, 실제 Series A 이사회 슬라이드처럼 보입니다. 구체적인 데이터, 구체적인 폰트, 구체적인 색상 조합을 사용합니다. 여러 페이지의 일관성은 edit endpoint를 통해 유지합니다. 중국어 포스터 및 광고— 설날 포스터, 제품 출시, 이벤트 커버. 따옴표 안의 정확한 텍스트 + 폰트 유형(楷书 / 黑体 / 思源黑体) + "no extra Chinese characters"로 마무리하여 렌더링이 깔끔합니다. 사실적인 UI mockup— 데스크톱 대시보드, 모바일 기기 등을 실제 기기 프레임 안에 배치하며, 문구는 실제처럼 작성합니다. Inter 폰트, 16진수 색상 코드, 합리적인 작업 명칭을 사용합니다. 픽셀 아트 및 게임 에셋— 캐릭터 sprite, 탑다운 타일셋(크로마키용 붉은색 사용), 아이템 아이콘, 캐릭터 삼면도, 장면 컨셉 아트. 인포그래픽— GPT Image 2가 실제로 렌더링할 수 있는 밀집된 텍스트 + 복잡한 구조. use-cases.md에 "How an Espresso Machine Works" 템플릿이 있습니다. Logo 컨셉— 2x2 변형 그리드를 통해 다양한 형태 언어(shape language)를 탐색합니다. Vector 스타일로 깔끔하며, 그라데이션이나 3D 효과가 없습니다. 사실적인 제품 사진— "고품질"이라는 말 대신 실제 사진 용어(50mm f/2.8, 북창광(north window light), 35mm 필름 그레인)를 사용합니다. 외과 수술 수준의 리터칭— change ONLY X / preserve Y exactly 모드. 객체 교체, 배경 변경, 스타일 전이(style transfer), mask를 이용한 부분 재생성(inpainting). 보고서 삽화 및 장식용 이미지— FT 스타일 편집 이미지, 수채화 챕터 삽화, 앱의 Empty state 캐릭터.

전체 가이드는 references/prompting.md에 있습니다. 한 문장으로 요약하자면: 마법 주문(magic spells)을 버리세요.

GPT Image 2 이전의 프롬프트 엔지니어링(prompt engineering)은 기본적으로 학습 데이터에 포함된 상투적인 표현들과 패턴 매칭을 하는 것이었습니다:

beautiful stunning ultra-detailed 4K 8K masterpiece trending on artstation
cinematic lighting professional photography premium quality

GPT Image 2는 이런 방식을 보상하지 않습니다. 대신 지시적이고, 구체적이며, 의도(intent)를 우선시하는 프롬프트를 보상합니다:

Create a pitch-deck slide titled "Q3 Revenue Performance" that looks
like a real Series A board-meeting slide. Layout (16:9): title top-left,
36pt Inter dark gray. Two-column body: left 60% chart, right 40% three
...

여기에는 포함되지 않았음에 주의하세요: 찬양하는 단어, "ultra detailed", "8K" 등이 없습니다. 모든 단어가 구체적인 지시 업무를 수행하고 있습니다.

Skill을 통해 Claude(또는 모든 agent)에게 규격화된 구조를 가르치세요:

의도 / 용도 → 장면 / 배경 → 주체 →
핵심 세부 사항 → 텍스트 내용 → 스타일 언어 → 제약 조건

여기에 7가지 습관을 더하세요: 의도로 시작하기, 모든 텍스트에 따옴표 사용하기, 찬양하는 언어 대신 사양(specification) 언어 사용하기, 리터칭 시 항상 "change ONLY X / preserve Y" 사용하기, 스타일 앵커(anchor)는 5개가 아닌 1개만 사용하기, 마법 주문 버리기, 반복 시 내용을 쌓아두지 않기.

미세하지만 거대한 개선 사항: skill은 Claude가 생성된 PNG를 직접 읽고(Read) 프롬프트와 대조하여 판단한 뒤, 사용자에게 보여주도록 합니다. 텍스트 렌더링이 맞게 되었는가? 구도가 말한 위치에 있는가? Negative prompt가 잘 지켜졌는가?

만약 틀린 부분이 있다면, agent는 한 번에 하나의 차원만 수정하여(prompting 가이드 참조) 다시 생성합니다. 사용자는 "내가 뭔가를 생성했는데 맞는지 봐줘"가 아니라, 합격점을 받은 결과를 보게 됩니다.

이것이 작동하는 이유는 Claude가 이미지를 볼 수 있기 때문입니다. 단지 기본적으로 자신이 생성한 것을 보지 않을 뿐입니다. skill은 바로 이 기본 설정을 바꾼 것입니다.

구현 세부 사항에 관심이 있다면:

Python 의존성 제로. CLI는 urllib, concurrent.futures, argparse만 사용합니다. requests도, openai도 없으며, 별도의 패키지 설치 단계도 필요 없습니다. 어떤 Python 3.7+ 환경에서도 실행 가능합니다. 클라이언트 측 병렬 처리. -n 4는 호스트에 4개의 이미지를 요청하는 것이 아니라, n=1인 요청을 4개 병렬로 보내는 방식입니다. 따라서 실제 소요 시간(wall-clock time)이 빠르며, 호스트가 n>1을 지원하는지 신경 쓸 필요가 없습니다. 합리적인 기본값. --quality high

(이 host는 각 품질 단계별 가격이 동일합니다)。--size 1024x1024

--concurrency 4

사전 검증 (Pre-validation). API 요청을 보내기 전에 해상도 제약 조건(가장 긴 변 <3840px, 비율 ≤3:1)을 확인하여 빠르게 실패(fail-fast)하고 명확한 정보를 제공합니다. 다중 이미지 입력에 대한 우아한 거부 (Elegant rejection of multi-image input). 이 host의 gpt-image-2는 한 번의 /edits 호출로 여러 장의 입력 이미지를 받는 것을 허용하지 않습니다. 스크립트는 조용히 실패하는 대신, 명확한 에러를 발생시키고 워크플로우 제안을 제공합니다.

이 모든 것들은 수정 가능합니다. fork한 후에 DEFAULT_QUALITY나 DEFAULT_BASE를 수정하거나, --watermark 플래그를 추가할 수 있습니다.

CLI 자체를 단독으로 실행할 수 있습니다. 배치 처리(Batch processing), 스크립트, 수동 탐색 모두에 유용합니다.

GI="python3 ~/.claude/skills/gpt-image-2/scripts/gpt_image.py"
# 생성
$GI generate -p "a misty mountain temple at dawn, Studio Ghibli watercolor" -o ./temple.png
...

cd ~/.claude/skills/gpt-image-2 && git pull

Skill은 텍스트 + 하나의 스크립트입니다. 빌드도, 재시작도, 등록도 필요 없습니다.

Fork를 하세요. 설계상 교체 가능한 부분은 다음과 같습니다:

— 여러분만의 스타일, 브랜드 컬러 팔레트, 자주 사용하는 소재 템플릿(자체 pitch-deck 템플릿, 자체 브랜드 hex 코드, 자체 인포그래픽 형식) 추가: references/use-cases.md

— scripts/gpt_image.py에 --watermark 플래그, 사용자 정의 출력 명명 규칙, S3 업로드, Slack 푸시 등을 자유롭게 추가

— 기본값 DEFAULT_BASE 대신 여러분의 프라이빗 게이트웨이(Private gateway)를 가리키도록 설정

에이전트(Agent)가 받는 시스템 프롬프트 (System prompt) — 만약 여러분의 에이전트가 자동으로 발견하지 못한다면 SKILL.md를 bootstrap에 연결하세요.

일반적인 변경 사항은 PR(Pull Request)을 환영합니다. 팀 특화적인 내용은 여러분의 fork에 남겨두세요.

MIT 라이선스입니다. LICENSE를 확인하세요. 마음대로 사용해도 됩니다.

Claude Code를 위해 만들어졌지만, 이 패턴(Markdown skill + 의존성 없는 CLI + 시각적 자가 검증)은 파일을 읽고 스크립트를 호출할 수 있는 모든 에이전트에 적용 가능합니다.

영감: OpenAI 공식 GPT Image 2 Cookbook, Anthropic의 superpowers/writing-skills에 관한 에이전트가 발견 가능한 skill 패턴.

이것을 Claude Code나 Codex에 넣으세요. 여러분의 에이전트는 "여기 curl 명령어가 있으니 행운을 빕니다" 수준에서 벗어나, 피치덱(pitch-deck) 슬라이드, 중국어 포스터, 픽셀 아트 타일셋, 실사 제품 사진, 그리고 정밀한 사진 편집을 단 한 번의 시도로 매번 완벽하게 수행하게 될 것입니다.

GPT Image 2는 2026년 4월에 출시되었습니다. 이는 세대적 도약입니다: 긴 지시 프롬프트(Instructional prompts)에서도 더 이상 세부 사항을 놓치지 않으며, 텍스트 렌더링이 마침내 정확해졌고(중국어/일본어/한국어 포함), 사용자 정의 해상도는 최대 3840px까지 지원되며, 편집 엔드포인트(Edit endpoint)는 change ONLY X / preserve Y exactly 패턴을 통해 정밀한 로컬 편집을 수행합니다.

하지만 여기에는 문제가 있습니다. 2026년 4월 이전에 훈련된 에이전트(agents)들은 이 모든 것을 알지 못합니다. 그들은 *

두 개의 환경 변수(environment variables). 이것이 전체 설정 범위(config surface)입니다.

변수 (Var)	필수 여부 (Required)	기본값 (Default)
OPENAI_IMAGE_API_KEY	예 (yes)	—
OPENAI_IMAGE_BASE_URL	아니오 (no)	https://jmrai.net/v1

이미지 전용 변수들이 설정되지 않은 경우, OPENAI_API_KEY / OPENAI_BASE_URL로 대체(fallback)됩니다.

크레딧 구매: https://order.jmrai.net

키(key)를 커밋하지 마세요. .gitignore는 .env를 제외합니다. .env.example은 템플릿일 뿐입니다.

다음은 전체 목록이 아닌 일부 샘플입니다 (references/use-cases.md에서 전체 카탈로그 확인 가능):

피치덱 슬라이드 (Pitch-deck slides)— 실제 Series A 이사회 슬라이드처럼 보입니다. 특정 데이터, 특정 폰트, 특정 팔레트를 사용합니다. 편집 엔드포인트(edit endpoint)를 통해 여러 슬라이드 간의 일관성을 유지합니다.

중국어 포스터 및 표지판 (Chinese posters & signage)— 인용된 텍스트 + 서체 스타일 (楷书 / 黑体 / 思源黑体) + "추가적인 중국어 글자 없음"이라는 접미사를 사용합니다. 선명하게 렌더링됩니다.

사실적인 UI 목업 (Realistic UI mockups)— 데스크톱 대시보드, 모바일 화면을 실제 기기 프레임 안에 그럴듯한 문구와 함께 구현합니다.

픽셀 아트 및 게임 에셋 (Pixel art & game assets)— 캐릭터 스프라이트(sprites), 탑다운 타일셋(top-down tilesets, 크로마키 마젠타 배경), 아이템 아이콘, 여러 각도의 캐릭터 참조 시트(reference sheets).

인포그래픽 (Infographics)— GPT Image 2가 실제로 정확하게 렌더링하는 수직형 정보 밀집 다이어그램입니다.

로고 컨셉 (Logo concepts)— 다양한 형태 언어(shape languages)를 탐색하는 2x2 그리드 변형입니다. 벡터처럼 깔끔하며, 그라데이션이나 3D 효과가 없습니다.

실사 제품 사진 (Photoreal product shots)— "프리미엄 품질(premium quality)" 같은 표현 대신 적절한 사진 용어(50mm f/2.8, 북향 창문 조명, 35mm 필름 그레인)를 사용합니다.

정밀한 사진 편집 (Surgical photo edits)— X만 변경 / Y는 정확히 유지(change ONLY X / preserve Y exactly) 패턴을 사용합니다.

보고서 도표 및 삽화 (Report figures & spot illustrations)— FT(Financial Times) 스타일의 편집용 다이어그램, 과슈(gouache) 섹션 삽화, 앱의 빈 상태(empty-state) 캐릭터.

전체 가이드는 references/prompting.md에 있습니다. 핵심은 **마법의 단어들을 버리는 것(drop the magic words)**입니다.

GPT-Image-2 이전의 프롬프팅 방식:

beautiful stunning ultra-detailed 4K 8K masterpiece trending on artstation
cinematic lighting professional photography premium quality

GPT Image 2는 이러한 방식에 보상하지 않습니다. 대신 지시적이고(instructional), 구체적이며(specific), 의도 우선적인(intent-first) 프롬프트에 보상합니다. 이 기술은 다음과 같은 정형화된 구조(canonical structure)를 가르칩니다:

의도 (Intent) → 장면 (Scene) → 대상 (Subject) → 세부 사항 (Details) → 텍스트 (Text) → 스타일 (Style) → 제약 사항 (Constraints)

여기에 7가지 습관을 더합니다: 의도를 먼저 명시할 것, 모든 캐릭터를 인용할 것, 찬사 위주의 언어가 아닌 사양(spec) 중심의 언어를 사용할 것, 수정 시 "X만 변경 / Y는 유지"라고 명시할 것, 스타일 닻(anchor)은 5개가 아닌 하나만 사용할 것, 마법의 주문(magic words)은 버릴 것, 쌓아 올리지 말고 반복(iterate)할 것.

이 기술은 Claude에게 사용자에게 보여주기 전, 생성된 PNG를 읽고 프롬프트와 대조하여 판단하도록 지시합니다. 만약 무언가 실패하면, 에이전트는 **한 번에 하나의 차원(one dimension at a time)**씩 반복하며 다시 생성합니다. 사용자는 "제가 이렇게 만들었는데, 맞나요?"라는 질문 대신 좋은 결과물을 보게 됩니다.

이것이 작동하는 이유는 Claude가 이미지를 볼 수 있기 때문입니다. 다만 기본 설정(default)으로는 자신이 생성한 것을 보지 않을 뿐입니다. 이 기술은 그 기본 설정을 바꿉니다.

Python 의존성 제로 (Zero Python deps). urllib, concurrent.futures, argparse만을 사용합니다. Python 3.7+ 환경이면 어디서든 실행됩니다. 병렬 배치 처리 (Parallel batching). -n 4는 API에 n=4를 요청하는 대신 4개의 병렬 단일 이미지 요청을 실행합니다. 실제 소요 시간(wall-clock)이 더 빠르며, 호스트의 n>1 지원 여부와 상관없이 작동합니다. 합리적인 기본값 (Sane defaults). 기본적으로 --quality high를 사용합니다 (이 호스트에서는 품질 등급 간 비용이 동일합니다). --size 1024x1024, --concurrency 4가 기본 적용됩니다. 사전 검증 (Upfront validation). API 왕복(round-trip) 전에 해상도 제약 조건(최대 변 길이 <3840px, 비율 ≤3:1)을 확인합니다. 다중 이미지 입력은 우아하게 거부됨 (Multi-image input gracefully refused). 이 호스트의 gpt-image-2는 /edits 호출당 여러 개의 입력 이미지를 허용하지 않습니다.

GI="python3 ~/.claude/skills/gpt-image-2/scripts/gpt_image.py"
$GI generate -p "a misty mountain temple at dawn, Studio Ghibli watercolor" -o ./temple.png
$GI generate -p "..." -n 4 --concurrency 4 -o ./out
...

cd ~/.claude/skills/gpt-image-2 && git pull

이 기술은 텍스트와 스크립트로 구성됩니다. 빌드 단계, 재시작, 등록 과정이 필요 없습니다.

포크(Fork)하세요. 교체 가능하도록 설계된 부분들은 다음과 같습니다:

— 자신만의 스타일, 브랜드 팔레트, 반복되는 에셋 템플릿 추가: references/use-cases.md

— scripts/gpt_image.py에 --watermark 플래그, 사용자 정의 출력 명명, S3 업로드 등을 추가

— 개인 게이트웨이를 가리키도록 설정: DEFAULT_BASE

추가하신 내용이 범용적(general-purpose)이라면 Pull request를 환영합니다.

MIT. LICENSE를 참조하세요.

원하는 대로 사용하세요.

Claude Code를 위해 제작되었으나, 이 패턴(markdown skill + 의존성 없는 CLI + 시각적 자기 검증 (visual self-verification))은 파일을 읽고 스크립트를 호출할 수 있는 모든 에이전트(agent)에서 작동합니다.

영감: OpenAI의 공식 GPT Image 2 Cookbook, Anthropic의 에이전트 발견 가능 기술 (agent-discoverable skills)을 위한 superpowers/writing-skills 패턴.