Create Explanatory Image

Create Explanatory Image

Purpose

Generate explanatory diagrams and infographics that clearly communicate a concept, iterating autonomously until the images are logically correct, text is accurate, and the visual explanation lands.

State Dependencies

Prerequisites

• GOOGLE_API_KEY or GEMINI_API_KEY set in .env
• Nano Banana image generator scripts available at .claude/skills/nano-banana-image-generator/scripts/

Inputs

• Concept description: What the diagram should explain (from user message or arguments)
• Output folder (optional): Where to save images. Default: auto-created folder named after the concept in current directory
• Style (optional): dark (black bg, brand style) or warm (charcoal bg, illustrated). Default: warm
• Aspect ratio (optional): 16:9, 1:1, 9:16. Default: 16:9
• Variant count (optional): How many initial variants. Default: 3

Process

Step 1: Read Current State

1. Read .claude/skills/nano-banana-image-generator/best_practices.md

   • Note complexity limits: 10 boxes max, 10 text labels max, 3 hierarchy levels max
   • Note known model limitations (misspellings on 4+ syllable words, font inconsistency)

2. Confirm output folder:

   • If user specified a folder, use it
   • Otherwise, create: [concept_slug]_diagrams/ in current directory
   • mkdir -p [folder]

Step 2: Decompose the Concept

Analyze the user's concept description and break it down:

1. Core message: What single insight should the viewer walk away with?
2. Visual elements: List all shapes, icons, nodes, connections needed
3. Text labels: List every text string that will appear in the image
4. Layout type: Identify the best diagram type:
   • Framework (central concept + surrounding elements)
   • Before/after comparison
   • Flow/process (horizontal or vertical)
   • Circular loop/cycle
   • Visual metaphor
   • Timeline/evolution
   • Cross-section/exploded view

Step 3: Simplify for Constraints

This step is critical. The concept decomposition will almost always exceed Nano Banana's limits. Simplify ruthlessly:

1. Count visual elements - if > 10, merge or remove until <= 10

2. Count text labels - if > 10, shorten labels to 1-2 words, replace words with icons, or remove sub-labels

3. Check word complexity - replace any word with 4+ syllables with a simpler alternative:

   Avoid (misspells)	Use Instead
   SOVEREIGNTY	OWN SPACE, ISOLATE
   ORCHESTRATION	COORDINATE, TEAMWORK
   HIERARCHICAL	TOP-DOWN, LEADER
   INFRASTRUCTURE	FOUNDATION, BUILD
   OBSERVABILITY	MONITOR, WATCH
   GOVERNANCE	CONTROL, AUDIT
   PLAYBOOK	(usually OK but occasionally garbles)

4. Verify hierarchy - max 3 levels: title, main content, footer

Present the simplified plan:

Concept: [one sentence]
Layout: [type]
Elements: [count] / 10 max
Labels: [count] / 10 max
Complex words replaced: [list]

Step 4: Generate Initial Variants

Generate the specified number of variants (default 3), each taking a slightly different visual approach to the same concept.

For each variant:

1. Craft a narrative prompt following best practices:

   • Write descriptive paragraphs, not keyword lists
   • Include style tokens (background color, text color, font)
   • Specify layout positioning explicitly
   • Request "generous spacing" and "clean minimal design"

2. Generate using the Python script (handles JSON escaping properly):

   python3 .claude/skills/nano-banana-image-generator/scripts/generate_image.py "[prompt]" /tmp/[concept]_v[N].png --aspect-ratio [ratio]

   Important: Use the Python script, not the bash script, to avoid JSON escaping issues with quotes in prompts.

3. Wait 2 seconds between API calls to avoid rate limits:

   sleep 2

Step 5: Self-Critique Loop

For each generated image, run this analysis cycle. This is the core differentiator of this skill.

1. View the image: Use the Read tool on the PNG file to visually inspect it

2. Check for issues against this checklist:

   • Title text: Is it spelled correctly and readable?
   • All labels: Are they spelled correctly? Any garbled/mushy text?
   • Element count: Does the image have roughly the right number of elements?
   • Logical structure: Does the layout match the requested concept? Are connections correct?
   • Missing elements: Is anything from the concept missing entirely?
   • Duplicate elements: Are any labels or nodes repeated incorrectly?
   • Text placement: Are labels in the right positions relative to their elements?
   • Readability: Would this be readable on a mobile screen?

3. Classify the image:

   • Good: No issues found, or only very minor ones. Keep as candidate.
   • Fixable: 1-2 specific issues that can be addressed by prompt adjustment. Iterate.
   • Redo: Fundamental layout/structure problems. Needs a different prompt approach.

4. For Fixable images, identify the specific fix:

   • Missing element -> Add explicit instruction for it
   • Misspelled word -> Replace with simpler word or remove
   • Wrong layout -> Be more explicit about positioning
   • Duplicate node -> Emphasize exact count ("exactly six nodes, not five, not seven")
   • Elements merged -> Use completely distinct words for each element

5. Regenerate with targeted fixes. Maximum 3 iteration rounds per variant.

6. Track the best version of each variant approach.