generate-image

name	generate-image
description	Generate game asset images from text descriptions using Replicate's nano-banana-pro model. Use this skill when the user asks to create or generate 2D images, sprites, textures, or visual assets for the game.

Generate Image Skill

Purpose

Generate game asset images using Replicate's nano-banana-pro model. This skill handles prompt optimization, API calls, and file management through a standalone executable script.

Inputs

• description (required): Text description of the asset (e.g., 'racing car', 'obstacle cube')
• assetType (optional): Type of asset ('vehicle', 'obstacle', 'prop', 'general')
• baseImagePath (optional): Path to existing image for image-to-image editing

Invocation

Run the standalone script with JSON arguments:

npx tsx /Users/tomek/projects/kata-workshop-cc/.claude/skills/generate-image/scripts/generate.ts '{
  "description": "red cube obstacle",
  "assetType": "obstacle"
}'

For image-to-image editing:

npx tsx /Users/tomek/projects/kata-workshop-cc/.claude/skills/generate-image/scripts/generate.ts '{
  "description": "red sports car with racing stripes",
  "assetType": "vehicle",
  "baseImagePath": "/Users/tomek/projects/kata-workshop-cc/public/images/generated/image_red_sports_car_20251203_153045.png"
}'

Output

The script outputs JSON to stdout:

{
  "imagePath": "/Users/tomek/projects/kata-workshop-cc/public/images/generated/image_red_cube_obstacle_20251203_153045.png",
  "prompt": "red cube obstacle, geometric, stackable, destructible appearance, 1:1 aspect ratio, white background, isometric view, game asset, suitable for 3D conversion, 1024px, clean edges, simple design, high quality render"
}

Progress messages are sent to stderr, so you can see them in the console but they won't interfere with JSON parsing.

How It Works

The script internally:

1. Optimizes the prompt using best practices for game assets:

   • Adds technical requirements: '1:1 aspect ratio, white background, isometric view'
   • Adds context: 'game asset, suitable for 3D conversion'
   • Adds quality directives: '1024px, clean edges, simple design'
   • Adds type-specific hints based on assetType:
     • vehicle: 'side view, wheels visible, streamlined design'
     • obstacle: 'geometric, stackable, destructible appearance'
     • prop: 'detailed, recognizable silhouette'

2. Calls Replicate API with the optimized prompt

   • Model: google/nano-banana-pro
   • Aspect ratio: 1:1
   • Output format: PNG
   • Safety tolerance: 5

3. Saves the image to /public/images/generated/

   • Filename format: image_{sanitizedDescription}_{timestamp}.png
   • Example: image_red_cube_obstacle_20251203_153045.png
   • Timestamps prevent overwrites

Error Handling

If an error occurs, the script:

• Exits with code 1
• Outputs JSON error to stderr: {"error": "error message"}

Common errors:

• REPLICATE_API_TOKEN not set: User needs to add API key to .env
  • Guide them to: https://replicate.com/account/api-tokens
• description is required: Missing required field in JSON input
• Replicate API error: API call failed (check network, API key, quotas)

Tools Required

• Bash: For executing the TypeScript script via npx tsx
• Read: For verifying the generated file (optional)

Success Criteria

• Script exits with code 0
• Valid JSON output with imagePath and prompt
• Image file exists at the returned path
• File is a valid PNG
• File size is reasonable (< 5MB)
• Image matches the description

Example Usage

Simple Generation

npx tsx .claude/skills/generate-image/scripts/generate.ts '{
  "description": "blue racing car",
  "assetType": "vehicle"
}'

Expected output:

{
  "imagePath": "/Users/tomek/projects/kata-workshop-cc/public/images/generated/image_blue_racing_car_20251203_154530.png",
  "prompt": "blue racing car, side view, wheels visible, streamlined design, 1:1 aspect ratio, white background, isometric view, game asset, suitable for 3D conversion, 1024px, clean edges, simple design, high quality render"
}

Image Editing

npx tsx .claude/skills/generate-image/scripts/generate.ts '{
  "description": "blue racing car with yellow racing stripes",
  "assetType": "vehicle",
  "baseImagePath": "/Users/tomek/projects/kata-workshop-cc/public/images/generated/image_blue_racing_car_20251203_154530.png"
}'

This will use the existing image as a base and apply the modifications.

Implementation Details

The script is located at: .claude/skills/generate-image/scripts/generate.ts

It imports shared utilities from:

• scripts/api/replicate.ts - Replicate API client
• scripts/utils/prompt-optimizer.ts - Prompt enhancement logic

This architecture ensures:

• Testability: Script can be tested independently
• Reusability: Same script works from any context
• Maintainability: Logic is centralized, not duplicated
• Version control: Clear tracking in git