---

name: diagram description: "Generate publication-quality technical diagrams using Nano Banana Pro (Gemini 3 Pro Image) with AI-powered quality review. Smart iteration only regenerates when quality is below threshold." allowed-tools: [Read, Write, Edit, Bash]

Nano Banana - Diagram Generation

Overview

Generate any technical diagram by describing it in natural language. Nano Banana Pro automatically creates publication-quality diagrams with intelligent quality review.

Key Features:

• 🍌 Smart Iteration: Only regenerates if quality is below threshold (saves API calls)
• 🎯 Document-Type Aware: Different quality standards for different document types
• 🔍 AI Quality Review: Gemini 3 Pro reviews each generation for professional standards
• 📊 Publication-Ready: High contrast, readable fonts, colorblind-friendly

When to Use This Skill

Use this skill when you need:

• Architecture Diagrams: System designs, microservices, C4 models
• Flowcharts: Process flows, decision trees, user journeys
• Data Models: ERD diagrams, schema visualizations
• Sequence Diagrams: API interactions, message flows
• Infrastructure Diagrams: Cloud architecture, deployment topologies
• Pipeline Diagrams: CI/CD, data pipelines, ML workflows
• Any Technical Visualization: Describe it, Nano Banana creates it

Quick Start

# Generate an architecture diagram
python skills/diagram/scripts/generate_diagram.py "Microservices architecture with API gateway, auth service, and database" -o architecture.png --doc-type architecture

# Generate a flowchart for a presentation
python skills/diagram/scripts/generate_diagram.py "User authentication flow with OAuth2" -o auth_flow.png --doc-type presentation

# Generate with verbose output
python skills/diagram/scripts/generate_diagram.py "Database schema for e-commerce" -o schema.png -v

Document Types & Quality Thresholds

Different documents have different quality requirements. Nano Banana automatically adjusts:

| Document Type | Threshold | Best For | |--------------|-----------|----------| | specification | 8.5/10 | Technical specs, PRDs | | architecture | 8.0/10 | Architecture documents | | proposal | 8.0/10 | Business proposals | | journal | 8.5/10 | Academic publications | | conference | 8.0/10 | Conference papers | | thesis | 8.0/10 | Dissertations | | grant | 8.0/10 | Grant proposals | | sprint | 7.5/10 | Sprint planning | | report | 7.5/10 | Technical reports | | preprint | 7.5/10 | arXiv, bioRxiv | | readme | 7.0/10 | README files | | poster | 7.0/10 | Academic posters | | presentation | 6.5/10 | Slides, talks | | default | 7.5/10 | General purpose |

Smart Iteration: If the first generation scores above the threshold, no second iteration is performed. This saves time and API costs.

Diagram Examples

System Architecture

python generate_diagram.py "Three-tier web application architecture with:
- React frontend
- Node.js API layer with load balancer
- PostgreSQL database with read replicas
- Redis cache layer
- CDN for static assets" -o three_tier.png --doc-type architecture

Sequence Diagram

python generate_diagram.py "Sequence diagram showing OAuth2 authorization code flow:
1. User clicks login
2. App redirects to auth server
3. User authenticates
4. Auth server returns code
5. App exchanges code for token
6. App accesses protected resource" -o oauth_flow.png --doc-type specification

Data Flow

python generate_diagram.py "Data pipeline showing:
- Data ingestion from multiple sources (API, files, streaming)
- ETL processing with Apache Spark
- Data warehouse (Snowflake)
- BI dashboards and ML model training" -o pipeline.png --doc-type report

C4 Model - Container Diagram

python generate_diagram.py "C4 Container diagram for e-commerce platform:
- Web App (React SPA)
- Mobile App (React Native)
- API Gateway (Kong)
- Order Service (Python)
- Payment Service (Go)
- Inventory Service (Java)
- PostgreSQL Database
- Redis Cache
- RabbitMQ Message Queue" -o c4_container.png --doc-type architecture

How It Works

1. Initial Generation: Nano Banana Pro (Gemini 3 Pro Image) generates the diagram
2. Quality Review: Gemini 3 Pro evaluates on 5 criteria:
   • Technical Accuracy (0-2 pts)
   • Clarity and Readability (0-2 pts)
   • Label Quality (0-2 pts)
   • Layout and Composition (0-2 pts)
   • Professional Appearance (0-2 pts)
3. Decision: If score ≥ threshold → Done! If score < threshold → Iterate
4. Improvement: Feedback is incorporated into an improved prompt
5. Regeneration: New diagram generated with improvements (max 2 iterations)

Output Files

For an output path of diagram.png, you'll get:

• diagram_v1.png - First iteration
• diagram_v2.png - Second iteration (if needed)
• diagram.png - Final version (copy of best iteration)
• diagram_review_log.json - Quality scores and review details

Configuration

Environment Variable (Recommended)

export OPENROUTER_API_KEY='your_api_key_here'

.env File

Create a .env file in your project:

OPENROUTER_API_KEY=your_api_key_here

Get Your API Key

1. Go to https://openrouter.ai/keys
2. Create a new API key
3. Add credits to your account

Tips for Better Diagrams

Be Specific

# ❌ Too vague
"System diagram"

# ✅ Specific and detailed
"Microservices architecture diagram showing user service, order service, and payment service communicating via REST APIs, with a shared PostgreSQL database and Redis cache"

Include Relationships

# ✅ Good - describes connections
"Data flow diagram showing:
- User uploads file to S3
- Lambda triggered on upload
- Lambda processes and stores metadata in DynamoDB
- SNS notifies downstream services"

Specify Style When Needed

# ✅ Style hints
"Flowchart with decision diamonds for the loan approval process, using green for approved paths and red for rejected paths"

Python API

from skills.diagram.scripts.generate_diagram_ai import NanoBananaGenerator

generator = NanoBananaGenerator(verbose=True)
results = generator.generate_iterative(
    user_prompt="Kubernetes cluster architecture with ingress, services, and pods",
    output_path="k8s_arch.png",
    iterations=2,
    doc_type="architecture"
)

print(f"Final Score: {results['final_score']}/10")
print(f"Early Stop: {results['early_stop']}")

Integration with Other Skills

• Use with sprint planning to visualize user story workflows
• Use with architecture research to diagram ADR decisions
• Use with building blocks to visualize component relationships
• Use with competitive analysis to create comparison diagrams

Troubleshooting

"OPENROUTER_API_KEY not found"

Set the environment variable or create a .env file. See Configuration section.

Low Quality Scores

• Add more detail to your prompt
• Specify relationships between components
• Use a higher threshold document type to force more iterations

Generation Timeout

Complex diagrams may take up to 2 minutes. The timeout is set to 120 seconds per API call.

Cost Considerations

• Gemini 3 Pro Image: ~$2/M input, ~$12/M output tokens
• Simple diagram (1 iteration): ~$0.05-0.15
• Complex diagram (2 iterations): ~$0.10-0.30
• Smart iteration saves costs by stopping early when quality is sufficient