create-explanatory-image

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

## Core Principles

Adapted from `/animated-explainer` - what makes an image *explain* rather than decorate.
Apply them at decomposition time (Steps 2-3); the self-critique loop (Step 5) checks them.

1. **The facts are the boss - interrogate before you design.** Decide what's TRUE before
   deciding what's compelling. If the image explains a real system, read its source of
   truth (specs, architecture docs, the actual data) - not marketing copy or published
   summaries. A concept the facts don't support dies at this step; that is the step
   working, not failing. Never soften an unsupported claim into a diagram.

2. **One concrete worked example beats any amount of abstraction.** A diagram that traces
   one real item end to end (this request, this invoice, this forecast) explains more
   than an abstract schema. Prefer a failure case the mechanism catches - it shows the
   machine doing its job and cannot be read as cherry-picking.

3. **Explainer, not advertisement.** Assume the viewer knows nothing. Open on the problem
   the mechanism solves - the title states what's broken or the single insight, not the
   product name. If the image only makes sense to someone who already understands the
   system, it has failed.

4. **Separate the mechanism from the numbers.** Carry the mechanism with symbolic marks;
   put real figures in ONE place (a footer stat, a single callout) or nowhere. If a mark
   is not 1:1 with a thing, say so on the image (`1 dot = ~30 runs`). Never silently mix
   scales. This also serves the 10-label limit.

5. **Lock the layout - nothing crosses anything.** One spine (a left-to-right flow or a
   single loop), elements sitting ON it. Crossing arrows read as *complexity*, not as a
   system. Prompt for it explicitly and reject renders where connections cross or wander.

6. **Nothing floats - every element visibly comes from somewhere.** The static cousin of
   "nothing teleports": causality is carried by explicit arrows and numbered steps
   (input -> transform -> output). An element with no incoming or outgoing connection is
   decoration - cut it or wire it in.

7. **Show the part that doesn't work.** If part of the system is unproven, planned, or
   broken, draw it dashed/hollow/greyed and label it. A diagram where everything works is
   the least trustworthy thing you can draw - the unfinished part is the credibility.

8. **Labels first.** Write every text string before generating anything (Step 2 does
   this) - if the labels alone, read in order, tell the story, the image will work. If
   they don't, no amount of visual polish will save it.

## 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. **Truth gate** (Principle 1): If the image describes a real system or carries real
   numbers, verify every claim against the source of truth (specs, docs, actual data) -
   never from memory or marketing copy. Cut anything unsupported and tell the user what
   was cut and why.
2. **Core message**: What single insight should the viewer walk away with? State it as
   the problem or insight, not the product name (Principle 3).
3. **Worked example** (Principle 2): Can the concept be shown as one concrete item traced
   end to end instead of an abstract schema? Prefer it; prefer a failure case the
   mechanism catches.
4. **Visual elements**: List all shapes, icons, nodes, connections needed. Every element
   must be wired into the flow (Principle 6) - an element with no incoming or outgoing
   connection gets cut or connected.
5. **Text labels**: List every text string that will appear in the image - then read them
   in order. If the labels alone tell the story, the image will work; if they don't, fix
   the story before generating anything (Principle 8).
6. **Honest state** (Principle 7): Which parts are live vs planned/unproven/broken? Mark
   the latter to render dashed, hollow, or greyed with a label.
7. **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:

From Abilityai/trinity-skills, Apache-2.0.

More from Abilityai/trinity-skills