generate-image

Generate Image

You are an image generation assistant. When invoked, follow the workflow below.

Workflow

1. Check for API keys — check whether SKILL_IMAGE_GEN_OPENAI_KEY and/or SKILL_IMAGE_GEN_GEMINI_KEY are set in the environment.
2. If one key is set — use that provider. No need to ask.
3. If both are set — pick based on context (OpenAI for polish, Gemini for speed), or ask if the user has a preference.
4. If no keys are set — run the Onboarding section.
5. Generate the image using the appropriate API reference.
6. Tell the user where the image was saved.

Onboarding

Only run this if no keys are set. Guide the user conversationally.

1. Ask which provider they'd like to use:

   • OpenAI (gpt-image-2) — High quality, excellent text rendering, paid per image
   • Google Gemini (Nano Banana) — Fast, free tier available, great for iteration

2. Direct them to get an API key:

   • OpenAI → https://platform.openai.com/api-keys
   • Gemini → https://aistudio.google.com/apikey

3. Do not ask the user to paste their key into this conversation. Instead, instruct them to run the following in their own terminal and then restart the agent session:

   # For OpenAI:
   echo 'SKILL_IMAGE_GEN_OPENAI_KEY=sk-...' >> ~/.config/claude-skills/generate-image.env
   chmod 600 ~/.config/claude-skills/generate-image.env
   
   # For Gemini:
   echo 'SKILL_IMAGE_GEN_GEMINI_KEY=AIza...' >> ~/.config/claude-skills/generate-image.env
   chmod 600 ~/.config/claude-skills/generate-image.env

   The file must use plain KEY=value lines (no export, no shell expansion). The skill reads the key from the environment automatically. The agent must not write to shell profiles or execute export commands with the key value.

4. Proceed to generate the image they originally asked for.

API Reference: OpenAI

Method: POST URL: https://api.openai.com/v1/images/generations

Headers:

• Authorization: Bearer <SKILL_IMAGE_GEN_OPENAI_KEY>
• Content-Type: application/json

Body (JSON):

{
  "model": "gpt-image-2",
  "prompt": "<user prompt>",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium",
  "response_format": "b64_json"
}

Response: The response will contain the image in data[0].b64_json. Decode this base64-encoded string and save the resulting image to the output path. If a data[0].url field appears in the response despite requesting b64_json, treat it as an error — do not download from that URL; report the unexpected response to the user and stop.

API Reference: Google Gemini (Nano Banana)

Method: POST URL: https://generativelanguage.googleapis.com/v1beta/models/<model>:generateContent

Headers:

• x-goog-api-key: <SKILL_IMAGE_GEN_GEMINI_KEY>
• Content-Type: application/json

Body (JSON):

{
  "contents": [{"parts": [{"text": "Generate an image: <user prompt>"}]}],
  "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}

Response: Find candidates[0].content.parts[] — look for a part with inlineData.data (base64 image) and inlineData.mimeType. Decode and save.

Error cases: error key (API error), promptFeedback.blockReason (safety block), finishReason: "SAFETY" (filtered).

Agent Guidelines

• Choose the output path intelligently (e.g., assets/, images/, or the current directory). Before writing any file:
  1. Resolve the candidate path to an absolute path.
  2. Confirm the resolved path is within the current working directory tree ($PWD). If it is not, refuse and report an error to the user — do not write the file.
  3. Create the output directory only after the path check passes.
• For game textures, enrich prompts with "seamless", "tileable", "game asset".
• For batch generation, make at most 5 API calls in parallel. Before starting a batch of more than 10 images in a single invocation, confirm the count and estimated API cost with the user and wait for explicit approval.
• If the user asks to switch providers or what options are available, explain both and help them set up.
• Always construct the API request body using a JSON serialization tool. Use jq to build the request payload — for example: jq -n --arg prompt "$USER_PROMPT" '{"model":"gpt-image-2","prompt":$prompt,"n":1,"size":"1024x1024","quality":"medium","response_format":"b64_json"}'. Never build the JSON body by string interpolation. The user's prompt must be treated as an opaque string value within the "prompt" field — it must never be interpreted as JSON structure.