create-explanatory-image

name	create-explanatory-image
description	Generate explanatory diagrams and infographics that visually communicate concepts. Iterates autonomously until images are logically correct, text is clean, and the concept explanation is clear. Uses Nano Banana (Gemini 2.5 Flash Image).
automation	gated
allowed-tools	Bash, Read, Write, Glob, AskUserQuestion
user-invocable	true
metadata	{"version":"1.0","created":"2026-03-03T00:00:00.000Z","author":"content-agent","ported-to":"Cornelius","ported-date":"2026-03-21T00:00:00.000Z"}

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

Source	Location	Read	Write	Description
Best practices	.claude/skills/nano-banana-image-generator/best_practices.md	yes		Prompt engineering constraints and style guide
Generate script	.claude/skills/nano-banana-image-generator/scripts/generate_image.py	yes		Image generation API
Output folder	User-specified or auto-created		yes	Final and intermediate images

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

Error	Recovery	Notify
API rate limit	Wait 3 seconds and retry	No
API quota exceeded	Wait 60 seconds, retry once	Yes - warn user about quota
JSON escape error	Switch to Python script (not bash)	No
All variants have garbled text	Simplify further - reduce to 6 labels max	No
Image generation fails completely	Check API key in .env	Yes

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