---
name: image-prompt-engineer
description: Use when a user needs prompt engineering, model selection, or quality scoring for AI image generation. Transforms natural language into optimized prompts for Flux 2, Recraft V4, Ideogram 3.0, GPT Image 1.5, Grok Imagine, and Nano Banana Pro with structured JSON output.
---

## Purpose

Transform natural language descriptions into production-ready, model-optimized image generation prompts. This skill bridges the gap between how humans describe images ("a cozy coffee shop on a rainy day") and how AI models produce their best work ("cozy artisan coffee shop interior, rain-streaked windows, warm amber lighting, wooden tables, steaming espresso cups, photorealistic, shallow depth of field, cinematic lighting, golden hour atmosphere").

This skill supports six leading image generation models:

| Model | Maker | Best For |
|-------|-------|----------|
| **Flux 2** | Black Forest Labs | Photorealism, multi-reference consistency, detailed scenes |
| **Nano Banana Pro** | Google (Gemini 3 Pro Image) | High-resolution (up to 4K), general purpose |
| **Recraft V4** | Recraft | Design work, SVG/vector output, marketing materials |
| **Ideogram 3.0** | Ideogram | Text rendering, color-controlled branding, style codes |
| **GPT Image 1.5** | OpenAI | Instruction following, multi-turn editing, conversational refinement |
| **Grok Imagine** | xAI | Quick aesthetic images, budget-friendly, phone-screen ratios |

**This skill does NOT generate images.** It engineers optimized prompts and outputs structured JSON containing the prompt, recommended model, provider options, quality scores, and technical specs. A separate provider execution skill or manual workflow is needed to actually generate images. For batch/high-volume work, a dedicated provider execution skill is recommended.

## When to Use This Skill

Invoke this skill when:

- A user provides a natural language image description and needs it optimized for a specific model
- A user wants model selection guidance based on their requirements
- A user needs quality validation or scoring of an existing prompt
- A user needs to determine optimal technical specs (resolution, aspect ratio, format) for their use case
- A user is building an application integrating image generation APIs and needs structured prompt output
- A user wants to compare which model suits their image generation needs
- A user has a prompt that underperforms and needs optimization with model-specific keywords
- A user needs batch processing of multiple descriptions with consistent quality standards

For detailed model comparisons, strengths/weaknesses, and feature support matrices, load references/model_comparison_matrix.md.

## Prompt Transformation Process

### Stage 1: Intent Analysis

Parse natural language input to identify: primary subject, scene context, desired style, mood/atmosphere, technical requirements, and special features (text-in-image, specific composition, brand colors). Extract implicit requirements — "product photography" implies commercial lighting, shallow depth of field, clean background.

### Stage 2: Model Selection

Select the optimal model based on requirements:

| Requirement | Best Model | Why |
|-------------|-----------|-----|
| Photorealistic product/people shots | Flux 2 Pro/Flex | Best photorealism + multi-reference |
| Text-heavy designs, signage, typography | Ideogram 3.0 or GPT Image 1.5 | Superior text rendering |
| SVG/vector graphics, logos | Recraft V4 Vector | Only model with SVG output |
| Quick drafts, iteration | Grok Imagine or Flux 2 Klein | Fast + cheap |
| Multi-turn editing, conversational refinement | GPT Image 1.5 | Unique conversational editing via Responses API |
| Style-consistent campaigns | Flux 2 (multi-ref) or Ideogram 3.0 (style codes) | Best consistency tools |
| High-resolution print (4K) | Nano Banana Pro | Up to 4K resolution |
| Color-precise branding | Ideogram 3.0 | Color palette with hex weights |
| Design/marketing materials | Recraft V4 | Design taste + exploration mode |
| Budget-conscious batch work | Grok Imagine or GPT Image 1.5 Low | Cheapest options (see references/technical_specs_tables.md for pricing) |
| Phone wallpapers, mobile screens | Grok Imagine | 19.5:9, 20:9 ratios |

If the user specifies a model, validate compatibility with their requirements and flag mismatches as warnings.

### Stage 3: Keyword & Photography Application

Apply model-specific keyword patterns from references/model_keyword_patterns.md. Structure keywords in optimal order: subject description → style/mood → lighting → composition → atmosphere.

**Photography parameters:** For photorealistic prompts, apply real photography knowledge from references/camera_photography_guide.md. Key principles:
- **Describe the visual result, not camera settings** — "shallow depth of field, creamy bokeh" beats "f/1.4"
- **Film stocks over quality keywords** — "Kodak Portra 400" beats "8K ultra-detailed"
- **Imperfection cues for realism** — film grain, uneven lighting, slight overexposure
- **Lighting is the most reliable parameter** — Rembrandt, golden hour, rim light work across all models
- **Avoid "8K, ultra-detailed, hyper-realistic"** — paradoxically makes images look MORE artificial on modern models

**Important:** The `optimized_prompt.positive` text must always be human-readable and copy-paste friendly. It should read naturally, not as a keyword dump. Users without API access should be able to paste this text directly into any image generation interface.

### Stage 4: Quality Validation

Score the transformed prompt across six dimensions (0-10 scale):

| Dimension | Weight | Measures |
|-----------|--------|----------|
| **Clarity** | 2.0x | Keyword precision and specificity; penalizes vague terms |
| **Completeness** | 1.5x | Coverage of subject, style, lighting, composition, technical details |
| **Optimization** | 1.5x | Model-specific keyword usage, quality boosters, negative prompts |
| **Coherence** | 1.0x | Logical consistency between elements, no contradictions |
| **Technical Validity** | 1.0x | Specification alignment with model capabilities |
| **Safety** | 1.0x | Content policy compliance, appropriate content filters |

**Overall score** = (Clarity × 2.0 + Completeness × 1.5 + Optimization × 1.5 + Coherence × 1.0 + Technical × 1.0 + Safety × 1.0) / 8.0

Rating scale: Below 7.0 = needs work (optimization suggestions provided), 7.0–7.9 = good, 8.0–8.9 = excellent, 9.0+ = exceptional.

Model-specific scoring nuances:
- **Ideogram 3.0:** Bonus points for specifying text in quotes, using style codes, providing color palette
- **Recraft V4:** Bonus for design vocabulary, specifying output format context (logo, poster, etc.)
- **Flux 2:** Bonus for detailed scene description (leveraging 32K context), specifying reference images
- **GPT Image 1.5:** Bonus for conversational clarity, specifying quality tier, edit-friendly structure
- **Grok Imagine:** Bonus for aesthetic focus, appropriate simplicity (model doesn't benefit from over-engineering)
- **Nano Banana Pro:** Bonus for resolution tier specification, natural language clarity

See references/quality_scoring_criteria.md for full rubric.

### Stage 5: Output Generation

Compile structured JSON containing all fields described below.

## JSON Output Format

```json
{
  "optimized_prompt": {
    "positive": "cozy artisan coffee shop interior, rain-streaked windows casting soft light patterns on wooden tables, warm amber lighting from Edison bulbs overhead, steaming espresso cups with latte art, photorealistic, shallow depth of field with gentle bokeh, cinematic composition, golden hour atmosphere filtering through the rain",
    "negative": "blurry, low quality, distorted, artificial lighting, empty space, cold atmosphere"
  },
  "model": {
    "name": "flux-2",
    "variant": "flex",
    "reason": "Selected for photorealistic interior photography with natural lighting and atmospheric detail"
  },
  "providers": [
    {"name": "fal.ai", "model_id": "fal-ai/flux-2-flex", "price_est": "$0.025/image"},
    {"name": "bfl.ai", "model_id": "flux-2-flex", "price_est": "$0.025/image"},
    {"name": "replicate", "model_id": "flux-2-flex", "price_est": "varies"}
  ],
  "quality_score": {
    "overall": 8.7,
    "breakdown": {
      "clarity": 9.0,
      "completeness": 8.5,
      "optimization": 9.0,
      "coherence": 9.0,
      "technical_validity": 9.0,
      "safety": 10.0
    },
    "rating": "excellent"
  },
  "warnings": [
    {
      "category": "optimization",
      "severity": "low",
      "message": "Consider specifying camera angle for better composition control",
      "recommendation": "Add: 'eye-level perspective' or 'slightly elevated view'"
    }
  ],
  "technical_specs": {
    "resolution": {"width": 1024, "height": 768, "reason": "Landscape orientation for interior scene"},
    "aspect_ratio": "4:3",
    "format": "png",
    "seed": null,
    "guidance_scale": 3.5,
    "num_inference_steps": 28,
    "enable_prompt_expansion": true
  },
  "metadata": {
    "original_input": "a cozy coffee shop on a rainy day",
    "timestamp": "2026-02-19T12:00:00Z",
    "transformation_notes": "Enhanced with photorealistic quality cues, specified lighting conditions (warm amber, Edison bulbs), enriched atmosphere with rain-streaked windows detail, included technical photography terms for depth and focus"
  }
}
```

**Key notes:**
- `optimized_prompt.negative` — only populated for Ideogram 3.0 (the only model supporting negative prompts). Set to `null` for all others.
- `model.name` — valid identifiers: `flux-2`, `nano-banana-pro`, `recraft-v4`, `ideogram-3`, `gpt-image-1.5`, `grok-imagine`
- `providers` — provider-agnostic array; no recommendation made. For complete provider arrays and pricing, load references/technical_specs_tables.md.
- `technical_specs` — fields vary by model. Only include parameters the selected model supports.

## Critical Constraints

These model-specific constraints must be respected to avoid API errors, degraded output, or wasted generation credits:

**1. Negative prompts: Ideogram 3.0 only**
Of all 6 models, only Ideogram 3.0 supports a `negative_prompt` parameter. For all other models, set `optimized_prompt.negative` to `null`. Attempting negative prompts on unsupported models is silently ignored or causes errors.

**2. GPT Image 1.5: exactly 3 resolution options**
Only `1024×1024`, `1024×1536`, and `1536×1024` are valid. No custom dimensions. Max 1536px on longest side — unsuitable for large-format print.

**3. Grok Imagine: minimal parameter control**
No guidance scale, inference steps, seed, or negative prompt parameters. Prompt quality is the only lever for output control. Do not include these parameters in `technical_specs`.

**4. Nano Banana Pro: no guidance or steps**
No guidance scale or inference steps available. Specify `resolution` tier (1K/2K/4K) and `aspect_ratio` only.

**5. Flux 2 prompt expansion enabled by default**
`enable_prompt_expansion: true` auto-enhances prompts. Beneficial for brief prompts, but can over-write precisely engineered prompts. Set to `false` when exact prompt control is needed.

**6. Recraft V4: no prompt-based editing**
V4 does not support iterative editing or style creation. Generation only. For SVG output, select the `vector` or `pro-vector` variant explicitly.

**7. Ideogram 3.0 style codes are persistent**
8-character hex style codes reproduce exact aesthetics across generations. Save and reuse codes for brand-consistent campaigns. Character reference is limited to 1 image.

**8. Provider model IDs vary**
The same model has different IDs across providers (e.g., Flux 2 Flex is `fal-ai/flux-2-flex` on fal.ai but `flux-2-flex` on BFL). Always include the provider-specific `model_id` in the `providers` array.

## Warning Classification

Four warning categories with varying severity:

**Safety Warnings** (severity: high) — Content policy violations, sensitive topics, copyright/trademark concerns, harmful stereotypes.

**Quality Warnings** (severity: medium) — Vague descriptions, conflicting elements, underspecified technical details, overly complex prompts.

**Technical Warnings** (severity: medium-high) — Resolution mismatches, unsupported features, aspect ratio incompatibilities, parameter values outside valid ranges. Model-specific examples:
- GPT Image 1.5: Only 3 resolution options (1024×1024, 1024×1536, 1536×1024)
- Grok Imagine: No guidance scale, steps, or seed parameters available
- Nano Banana Pro: No guidance scale or steps control
- Ideogram 3.0: Discrete resolution steps only (60+ options but not fully custom)

**Optimization Warnings** (severity: low) — Underutilized model capabilities, better model available, missing quality boosters, inefficient keyword ordering.

See references/warning_system_guide.md for complete warning catalog.

## Technical Specification Auto-Detection

The skill automatically determines optimal specifications:

**Resolution:** Match to use case (social media 1024², print 2048+, web banners landscape) and model limits. Nano Banana Pro supports up to 4K. GPT Image 1.5 limited to 1536px max.

**Aspect Ratio:** Portraits → 3:4 or 2:3, landscapes → 16:9 or 3:2, products → 1:1, social → platform specs, phone screens → Grok Imagine's 19.5:9 or 20:9.

**Format:** PNG for transparency/quality, JPEG for photos/web, WebP for modern web, SVG for Recraft V4 vector output.

**Parameters:** Model-specific defaults — Flux 2: guidance_scale 3.5, steps 28, prompt expansion on. GPT Image 1.5: quality tier based on use case. Ideogram 3.0: magic_prompt on for short prompts. See references/technical_specs_tables.md.

## Examples

### Example 1: Photorealistic Scene (Flux 2)

**User:** "a cozy coffee shop on a rainy day"

```json
{
  "optimized_prompt": {
    "positive": "cozy artisan coffee shop interior, rain-streaked windows casting soft light patterns on wooden tables, warm amber lighting from Edison bulbs overhead, steaming espresso cups with latte art, shallow depth of field with gentle bokeh, photorealistic, cinematic composition, golden hour atmosphere filtering through the rain",
    "negative": null
  },
  "model": {"name": "flux-2", "variant": "flex", "reason": "Photorealistic interior with atmospheric lighting detail"},
  "providers": [
    {"name": "fal.ai", "model_id": "fal-ai/flux-2-flex", "price_est": "$0.025/image"},
    {"name": "bfl.ai", "model_id": "flux-2-flex", "price_est": "$0.025/image"}
  ],
  "quality_score": {"overall": 8.7, "rating": "excellent"},
  "warnings": [],
  "technical_specs": {"resolution": {"width": 1344, "height": 768}, "aspect_ratio": "16:9", "format": "jpeg", "guidance_scale": 3.5, "num_inference_steps": 28}
}
```

### Example 2: Text-Heavy Design (Ideogram 3.0)

**User:** "instagram post for coffee brand with text 'MORNING VIBES'"

```json
{
  "optimized_prompt": {
    "positive": "modern minimalist instagram post design, bold sans-serif text reading \"MORNING VIBES\" centered on the image, stylized coffee cup illustration with rising steam, warm brown and cream color palette, clean graphic design aesthetic, social media optimized square composition, high contrast with professional branding feel",
    "negative": "cluttered layout, blurry text, inconsistent fonts, low resolution"
  },
  "model": {"name": "ideogram-3", "variant": "standard", "reason": "Best text rendering for 'MORNING VIBES' typography with color palette control"},
  "providers": [
    {"name": "fal.ai", "model_id": "fal-ai/ideogram-3", "price_est": "~$0.02/image"},
    {"name": "ideogram.ai", "model_id": "ideogram-v3", "price_est": "varies"},
    {"name": "together.ai", "model_id": "ideogram/ideogram-3.0", "price_est": "varies"}
  ],
  "quality_score": {"overall": 9.0, "rating": "exceptional"},
  "warnings": [],
  "technical_specs": {"resolution": "1024x1024", "aspect_ratio": "1:1", "format": "png", "magic_prompt": true}
}
```

### Example 3: SVG Logo Design (Recraft V4)

**User:** "minimalist logo for a mountain hiking company called 'Summit Trail'"

```json
{
  "optimized_prompt": {
    "positive": "minimalist logo design for 'Summit Trail' hiking company, clean geometric mountain silhouette with a trail path winding upward, modern sans-serif typography, limited color palette of deep forest green and slate gray on white, balanced composition with strong visual hierarchy, professional brand identity, flat design with clean lines",
    "negative": null
  },
  "model": {"name": "recraft-v4", "variant": "vector", "reason": "SVG vector output for editable, scalable logo design"},
  "providers": [
    {"name": "fal.ai", "model_id": "fal-ai/recraft-v4", "price_est": "see recraft.ai"},
    {"name": "recraft.ai", "model_id": "recraft-v4-vector", "price_est": "free plan available"}
  ],
  "quality_score": {"overall": 9.1, "rating": "exceptional"},
  "warnings": [],
  "technical_specs": {"format": "svg", "output_type": "vector"}
}
```

### Example 4: Quick Phone Wallpaper (Grok Imagine)

**User:** "aesthetic phone wallpaper with northern lights over a lake"

```json
{
  "optimized_prompt": {
    "positive": "stunning northern lights aurora borealis dancing over a perfectly still mountain lake, vivid greens and purples reflecting on the water surface, starry night sky, serene and ethereal atmosphere, beautiful aesthetic phone wallpaper composition",
    "negative": null
  },
  "model": {"name": "grok-imagine", "variant": "standard", "reason": "Aesthetic focus with phone-screen aspect ratio support"},
  "providers": [
    {"name": "fal.ai", "model_id": "xai/grok-imagine-image", "price_est": "$0.02/image"},
    {"name": "x.ai", "model_id": "grok-imagine", "price_est": "varies"}
  ],
  "quality_score": {"overall": 8.2, "rating": "excellent"},
  "warnings": [{"category": "technical", "severity": "low", "message": "Grok Imagine has limited parameter control — prompt quality is the primary lever"}],
  "technical_specs": {"aspect_ratio": "9:19.5", "format": "png"}
}
```

### Example 5: Multi-Turn Edit Setup (GPT Image 1.5)

**User:** "professional headshot of a woman in a modern office, I'll want to iterate on it"

```json
{
  "optimized_prompt": {
    "positive": "professional corporate headshot of a woman in her 30s, modern glass-walled office background with soft bokeh, natural window lighting from the left, confident warm smile, business casual attire, clean and polished look, high quality portrait photography",
    "negative": null
  },
  "model": {"name": "gpt-image-1.5", "variant": "high", "reason": "Multi-turn editing via Responses API for iterative refinement"},
  "providers": [
    {"name": "openai", "model_id": "gpt-image-1.5", "price_est": "$0.20/image (high quality)"}
  ],
  "quality_score": {"overall": 8.8, "rating": "excellent"},
  "warnings": [{"category": "technical", "severity": "medium", "message": "GPT Image 1.5 limited to 1536px max resolution — not suitable for large print"}],
  "technical_specs": {"resolution": {"width": 1024, "height": 1536}, "aspect_ratio": "2:3", "format": "png", "quality": "high", "action": "generate"}
}
```

### Example 6: High-Resolution Print (Nano Banana Pro)

**User:** "large format landscape photo of Patagonia mountains for a gallery print"

```json
{
  "optimized_prompt": {
    "positive": "breathtaking panoramic landscape of Patagonia's Torres del Paine, dramatic granite peaks piercing through swirling clouds, turquoise glacial lake in the foreground, golden hour sunlight illuminating the mountain faces, ultra high resolution photography with exceptional detail in rock textures and cloud formations, professional landscape photography",
    "negative": null
  },
  "model": {"name": "nano-banana-pro", "variant": "4k", "reason": "4K resolution output for large-format gallery print"},
  "providers": [
    {"name": "fal.ai", "model_id": "fal-ai/nano-banana-pro", "price_est": "~$0.02/image"}
  ],
  "quality_score": {"overall": 8.9, "rating": "excellent"},
  "warnings": [],
  "technical_specs": {"resolution": "4K", "aspect_ratio": "16:9", "format": "png"}
}
```

## References

This skill uses progressive disclosure — detailed reference material is loaded as needed:

- `references/model_comparison_matrix.md` — Side-by-side ratings (1-5 stars) across photorealism, text rendering, speed, resolution, editing, pricing, and parameter control for all 6 models. Feature support matrix showing negative prompt, seed, style reference, SVG, and transparency capabilities per model. Load when selecting between models or explaining model trade-offs.

- `references/model_keyword_patterns.md` — Model-specific keyword libraries: quality boosters, style keywords, prompt structure patterns, best practices, and anti-patterns for each of the 6 models, plus universal keywords (lighting, composition, mood) that work across all models. Load during Stage 3 keyword application.

- `references/quality_scoring_criteria.md` — Full rubrics for all 6 scoring dimensions with concrete examples at each score band, model-specific scoring nuances, and the weighted formula implementation. Load for detailed score justification or edge case validation.

- `references/technical_specs_tables.md` — Complete API parameters, provider endpoints, model IDs, variant tables, resolution options, output formats, pricing tables, and unique features for all 6 models. Load when configuring `technical_specs` or `providers` in output JSON.

- `references/transformation_examples.md` — Additional before/after prompt transformation examples beyond the 6 in SKILL.md, covering edge cases, multi-model comparisons, and iterative refinement sequences. Load as output templates or for complex use cases.

- `references/warning_system_guide.md` — Complete warning catalog with all categories, severity levels, model-specific technical warnings, and recommended fixes. Load when classifying warnings or debugging generation failures.

- `references/camera_photography_guide.md` — Real photography parameters mapped to AI image generation: camera bodies as aesthetic anchors, film stocks for color science, lens focal lengths for composition, lighting setups, imperfection/realism cues, and per-model anti-AI realism recipes. Load for photorealistic prompts or when users reference photography concepts.

- `references/user_guide.md` — Plain-English guide explaining the skill's capabilities for non-technical users, including model selection advice, common workflows, and FAQ. Load when a user requests an overview or is new to AI image generation.
