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