Image Generation Skill (Gemini & Whisk)

Use this skill to generate character art using Google's AI tools. This approach uses the unified image-gen MCP server or the agent's native devtools tools to drive the browser.

Prerequisites

Chrome Browser: The script scripts/workflows/gemini/core/image-gen-mcp.ts manages the browser session (launching chrome with a persistent profile).
- Manual Login: Required on the first run. The script will pause and alert you if you are not logged in.
Unified MCP Server:
- Server Name: image-gen
- Tools: generate_image, download_image, verify_image_adherence

Core Learnings & Obstacles

Whisk vs. Gemini: Whisk (labs.google) is highly reactive and often ignores automated clicks. Gemini (gemini.google.com) is much more stable and is the default provider for the unified tool.
Visual Verification: Use verify_image_adherence to check generated images against the "Full Body D&D Villager" guidelines. This tool re-uploads the image to Gemini and asks for a critique.
One-Turn Search & Generate: Gemini can handle "Search then Generate" in a single prompt. This is faster and more accurate than doing it in two steps.

Workflow

1. Launch & Connect

The script handles launching automatically.

Run the server or script: npx tsx scripts/workflows/gemini/core/image-gen-mcp.ts
If it's your first time, the window will open. Log in to Google.
Once logged in, the script will be ready to accept tool calls.

2. Optimized Prompting (Two-Step Strategy)

To ensure accuracy and "mundane/slice-of-life" grounding, use a two-step approach.

Step 1: Research & Describe

"Research the visual characteristics of the [Race] race from canon D&D 5e sources. Focus on: physical appearance (skin, features, build), typical mundane habitat, and typical clothing for a COMMON VILLAGER or WORKER (not an adventurer/hero).

based on this, write a detailed visual description of a [Gender] [Race] Villager in a slice-of-life setting. The description should be vivid and suitable for image generation. DO NOT generate an image yet."

Step 2: Generate

"Generate a high-quality, detailed fantasy illustration based on the description above. D&D 5e art style. Full body view, showing the character from head to toe. Aspect ratio 1:1 (square)."

3. Submission & Interaction

Use evaluate_script to insert text and click send (see Fast-Path Automation below).
Always wait for the first response to complete (approx 10-15s) before sending the second prompt.

4. Downloading & Renaming

Use the download_image tool. It automatically handles finding the high-res URL or clicking the download button.

Tool Call: download_image(outputPath: "absolute/path/to/Parent_Subrace_Gender.png")
Path Convention: public/assets/images/races/[Parent]_[Subrace]_[Gender].png (TitleCase).
- Example: Elf_Wood_Male.png
- Example: Dragonborn_Red_Male.png
- Example: Aarakocra_Female.png (No subrace)

5. Verification

Use the verify_image_adherence tool to ensure quality.

Tool Call: verify_image_adherence(imagePath: "...")
Guidelines Checked: Full Body (Head to Toe), Common Villager/Worker, Slice-of-Life, D&D 5e Style.
Action: If verification returns complies: false, consider regenerating the image.

6. Layout Consistency

Sizing: To ensure race images aren't "huge," generate both Male and Female (or two variations) for every race. This triggers the hasDualImages layout in the glossary, which uses small thumbnails instead of full-card width.

6. Automated Wiring & Auditing

Use the scripts/audit_and_wire_images.ts script to automatically:

Rename files to the Parent_Subrace_Gender.png convention.
Wire the new paths into src/data/races/*.ts and glossary/*.json.
Audit for missing wiring.

Run with: npx tsx scripts/audit_and_wire_images.ts

7. Cleanup & Efficiency

New Chat Protocol: The script automatically handles "New Chat" logic when necessary to avoid context bleed.
Session Reset: If you encounter issues, kill the terminal and run taskkill /F /IM chrome.exe /T to fully reset the browser.
Fast-Path Automation: To save tokens and time, avoid take_snapshot for known static elements. Use evaluate_script with stable CSS selectors:

8. Implementation (Linking Images)

You must wire up the images in TWO places: the Glossary (JSON) and the Character Creator (TypeScript).

A. Glossary Data (JSON)

Open public/data/glossary/entries/races/[race].json.

Add/Update:

"maleImageUrl": "/assets/images/races/[race]_male.png",
"femaleImageUrl": "/assets/images/races/[race]_female.png"

B. Character Creator Data (TypeScript)

Open src/data/races/[race].ts.

Update the visual object within the race constant:

visual: {
  // ... keep existing icon/color
  maleIllustrationPath: 'assets/images/races/[race]_male.png',
  femaleIllustrationPath: 'assets/images/races/[race]_female.png',
},

(Note: No leading slash for the TS file paths)

Status Checklist (as of 2026-01-20)

Completed:

Missing Subraces (To-Do):

Elves:

Dwarves:

Mountain Dwarf (Male)
Mountain Dwarf (Female)
Runeward Dwarf (Male)
Runeward Dwarf (Female)

Gnomes:

Halflings:

Dragonborn (Chromatic/Metallic/Gem):

Tieflings:

Infernal Tiefling (Male)
Infernal Tiefling (Female)
Chthonic Tiefling (Male)
Chthonic Tiefling (Female)

Aasimar:

Goliaths:

Shifters:

Eladrin:

Humans (Variants):

Half-Elves (Variants):

Completion Criteria

Before concluding any image generation task, you must satisfy the following checklist:

Visual Adherence: Confirm that the generated image has been validated using the visual verification checks (adhering to Full Body view, common D&D villager aesthetic, slice-of-life setting).
File Naming: Verify the image is saved to public/assets/images/races/ and is named strictly under the Parent_Subrace_Gender.png title-case convention.
Double Variation: Confirm that both Male and Female illustrations are generated and successfully saved to trigger the correct dual-image card layout in the UI.
Data Wiring: Run npx tsx scripts/audit_and_wire_images.ts and confirm that all new image paths are successfully wired into the glossary JSON files and Character Creator TypeScript definitions.
No Broken Links: Verify the images load correctly on the front-end without rendering missing resource fallbacks or broken image placeholders.

whisk-image-generation