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.

Step 6: Present Candidates

[APPROVAL GATE] - Present the best candidates to the user

Show each candidate image and describe:

• What it got right
• Any remaining minor imperfections
• Which concept angle it takes

User options:

1. Pick a winner - Select one or more as final
2. Iterate on specific one - Request changes to a candidate
3. New direction - Describe a different visual approach
4. Combine elements - Mix aspects from multiple candidates

If user requests changes:

• Apply modifications to the prompt
• Regenerate and re-run self-critique (Step 5)
• Return to this gate

Step 7: Finalize and Cleanup

1. Copy final images to the output folder with clean names:

   cp /tmp/[best_version].png [output_folder]/[concept_name].png

2. Delete intermediate files from /tmp:

   rm /tmp/[concept]_v*.png

3. Keep only final versions in the output folder. Delete any intermediate copies.
4. Open the output folder for the user:

   open [output_folder]

Step 8: Write Completion Summary

Report:

## Generated Images

**Concept**: [description]
**Output**: [folder path]
**Files**: [list of final files]
**Iterations**: [total attempts] across [variants] variants
**Cost**: ~$[0.039 * total_attempts] ([total] images generated)

Outputs

• Final explanatory images in the output folder
• All intermediate files cleaned up

Error Recovery

Completion Checklist

• Best practices read fresh
• Concept decomposed and simplified to constraints
• Initial variants generated
• Each variant self-critiqued for text accuracy and logical correctness
• Best candidates presented and approved by user
• Final images saved to output folder with clean names
• Intermediate files deleted
• Output folder opened for user

Style Reference

Warm style (default):

Warm charcoal background (#2D2926), soft cream text (#FAF8F5),
illustrated flat design with soft shadows, DM Sans font style,
dusty rose (#D4A5A5), coral (#E8B4A0), muted teal (#7BA3A3),
soft gold (#D4C4A0) accent colors.

Dark brand style (the user's):

Black background (#000000), white text (#ffffff), DM Sans font,
bold 700 weight for titles, clean minimal design, high contrast.

Self-Improvement

After completing this skill's primary task, consider tactical improvements:

• Review execution: Were there friction points, unclear steps, or inefficiencies?
• Common failure patterns: Did certain types of prompts consistently fail? Add to the word replacement table.
• Iteration efficiency: Did self-critique catch real issues or waste cycles on false positives?
• Prompt patterns: Did any prompt structure produce consistently better results? Document it below.
• Apply improvement (if identified):
  • Edit this SKILL.md with the specific improvement
  • Keep changes minimal and focused
• Version control (if in a git repository):
  • Stage: git add .claude/skills/create-explanatory-image/SKILL.md
  • Commit: git commit -m "refactor(create-explanatory-image): <brief improvement description>"

Learned Patterns

• "playbook" frequently misspells as "playbaak" or "playbauk" - avoid in taglines, use "it" or "the file" instead
• EDIT and SAVE merge into one label when used as adjacent cycle nodes - use completely distinct words (RUN/CHECK/STORE/REFLECT/REFINE/PUSH)
• Circular diagrams with 6+ nodes tend to duplicate labels - stick to 3-4 nodes max for loops
• The Python generate_image.py script handles JSON escaping; the bash generate.sh does not - always prefer Python for complex prompts
• Explicitly state "exactly N nodes, not more, not fewer" when count precision matters
• Labels OUTSIDE circles/nodes render more reliably than labels inside
• Use numbered lists (1. READ STATE, 2. DO WORK) to force correct vertical stacking