docs-image

name	docs-image
description	Generate AI illustrations (hero, cover, conceptual, infographic) for nexus-agents docs via the nanobanana-mcp gateway. Use when the user needs a hero image, README cover, or conceptual illustration. NOT for precise architecture diagrams — those redirect to docs-mermaid. NOT for quantitative charts — those redirect to docs-chart. Triggers on "generate image", "blog image", "hero image", "cover image", "illustration".
allowed-tools	Read, Edit, Write, Bash, Grep, Glob

AI Illustrations Skill

When to apply

Use AI image generation in three specific cases:

1. Hero / cover images — README header, blog post cover, major architecture doc landing image
2. Conceptual illustrations — abstract / editorial mode for "what consensus voting feels like" — illustrative, not load-bearing
3. Infographic-mode visualizations — shape of an approach, layered process flows where "approximate shape" beats "exact byte path"

For everything else, redirect.

Step 1 (CRITICAL) — Mermaid-first check

Before generating, ask: "Is this a 'show how X works' question with precise components / sequence / state?"

If YES → recommend docs-mermaid. State the rule of thumb: "Mermaid wins for precise diagrams: it's text-based, diff-able, and renders accurately. AI images are wrong for this — they look right until you check the details."

If NO and the request is genuinely illustrative ("show me what consensus feels like", "hero for the README"), proceed to step 2.

This guardrail is the highest-priority rule in the skill. Skipping it produces architecture diagrams that look plausible but are wrong in detail.

Step 2 — Select domain mode

Mode	When to use	Prompt emphasis
Infographic (default)	Layered process shape, comparison panels	Layout structure, hierarchy, accessible colors
Editorial	Hero / blog cover with mood	Composition, lighting, publication references
Abstract	Pattern background, decorative section divider	Color theory, mathematical forms, textures
UI/Web	Tech illustration with vector / flat-design feel	Clean lines, exact colors, icon-style

Defaulting to Infographic is correct for ~80% of nexus-agents use cases — most requests are about explaining a process, not setting a mood.

(Product / Landscape modes from upstream are intentionally omitted — this is a code-governance project, not e-commerce or travel.)

Step 3 — Construct the 6-component prompt

Build the prompt as a natural narrative paragraph using the 6-component reasoning brief:

1. Subject — who/what, with rich physical detail
2. Action — what's happening
3. Context — environment / setting
4. Composition — framing, perspective, focal point
5. Lighting — mood, time of day, light source
6. Style — visual treatment (Infographic / Editorial / etc.)

Never pass raw user text directly to the API. Always interpret + enhance.

See references/prompt-engineering.md for full per-mode modifier libraries and worked examples.

Step 4 — Generate via nanobanana-mcp

Tool: mcp__nanobanana__generate_image
Prompt: <constructed prompt from step 3>
Aspect ratio: 16:9 (hero / OG card) or 4:3 (inline)
Resolution: 1200x630 for OG, 1920x1080 for hero

If nanobanana-mcp is not configured:

1. Try calling get_image_history (lightweight, no side effects)
2. If it fails: inform the user "Image generation requires the nanobanana-mcp server. See references/prompt-engineering.md for setup."
3. When called internally (from a doc generation workflow): return silently — the calling workflow continues without the image.

Operational considerations

• Costs money per image (Gemini Imagen pricing ≈ $0.039/image at time of writing). Always announce cost-per-call before generating more than one image.
• Regenerate sparingly. Iterate on the prompt before committing budget; one carefully-constructed prompt beats five quick attempts.
• Save outputs to a documented location. Hero images in docs/architecture/images/; blog covers in <post-dir>/cover.png. Never to /tmp or scratch dirs.

Cross-references — when to redirect

This is the illustrative-images lane. Redirect when the request fits elsewhere:

• Sequence / state / flow / class / ER → docs-mermaid
• Bar / donut / line / lollipop chart → docs-chart
• Doc structure / placement → documentation-management

When you redirect, state the rule of thumb so the user calibrates for next time.

What this skill does NOT do

• Architecture diagrams. Mermaid wins on accuracy + diff-ability.
• Quantitative charts. SVG wins on precision.
• Image editing pipelines beyond what nanobanana-mcp supports natively. Defer to next round if needed.
• Local generation (Stable Diffusion / etc.). Operator opts into Gemini via the MCP server.

See also

• references/prompt-engineering.md — domain-mode modifier library + worked examples
• references/setup-nanobanana.md — MCP server setup walkthrough (TBD — file as a follow-up if operators ask)