# Image Prompt Engineer — User Guide

A plain English guide for getting the best image generation prompts, even if you've never touched an API.

---

## 1. What This Skill Does

When you want to create an image with AI, you type a description — something like "a sunset over the ocean." But AI image generators work much better when you describe things in a very specific way, with the right words, in the right order, for the right model.

**This skill is your prompt translator.** You describe what you want in plain English, and it gives you back:

- An **optimized prompt** — a carefully crafted description that gets the AI to produce much better results
- A **model recommendation** — which AI image generator is best for what you want
- A **list of providers** — where you can actually generate the image (with estimated costs)
- A **quality score** — how effective your prompt is likely to be (0–10 scale)
- **Warnings** — things that might cause problems (wrong resolution, conflicting styles, etc.)
- **Technical settings** — resolution, aspect ratio, and other parameters tuned for your use case

Think of it like having a professional photographer translate your casual description into precise camera settings and composition directions.

## 2. What This Skill Does NOT Do

**This skill does not generate images.** It only creates the optimized prompt and settings.

To actually create an image, you need to take the output and use it with an image generation service (like Fal.ai, OpenAI, Recraft, or others). The skill tells you exactly where to go and what settings to use.

Think of it like a recipe — this skill writes the recipe, but you still need a kitchen to cook it.

For high-volume or batch image generation, a separate provider execution skill is recommended.

## 3. How to Install

### Claude Code (Terminal)

If you use Claude Code in your terminal, this skill is already available as part of your workspace skills. No installation needed — just start using it.

### Claude Desktop

1. Open Claude Desktop settings
2. Go to **Features** → **Skills** (or **Projects**)
3. Add a new project/skill folder pointing to: `skills/image-prompt-engineer/`
4. Include `SKILL.md` and the `references/` folder
5. Start a new conversation — Claude will now have prompt engineering capabilities

### Claude Web (claude.ai)

1. Start a new conversation on claude.ai
2. Click the **paperclip icon** (attachments)
3. Upload `SKILL.md` as a file attachment
4. Optionally upload reference files from the `references/` folder for deeper model knowledge
5. Tell Claude: "Use the attached skill to optimize my image prompts"

**Tip:** For the best results on Claude Web, also upload `references/model_keyword_patterns.md` and `references/technical_specs_tables.md`.

## 4. How to Use It

Just describe what image you want. Here are some examples:

**Simple:**
> "Make me a prompt for a sunset over the ocean"

**With a specific model:**
> "I need a prompt for Recraft V4 — a minimalist logo for a tea company called 'Leaf & Stone'"

**With a use case:**
> "I need an Instagram post image for my bakery's grand opening"

**With constraints:**
> "Phone wallpaper of northern lights, keep it cheap"

**Comparing options:**
> "Which model should I use for a realistic product photo of sneakers?"

**Improving an existing prompt:**
> "I've been using this prompt but the results aren't great: 'beautiful mountain landscape sunrise'. Can you optimize it?"

You don't need to know anything about models, parameters, or APIs. Just describe what you want, and the skill handles the rest.

## 5. Understanding the Output

The skill returns a JSON block. Here's what each part means:

### The Prompt (Most Important Part)

```
"optimized_prompt": {
  "positive": "your optimized prompt text here",
  "negative": "things to avoid (only for some models)"
}
```

The **positive** prompt is the main text you'll copy and paste. It's written in plain English — you can read it and it makes sense. This is what you feed into the image generator.

The **negative** prompt tells the AI what to avoid (like "blurry, low quality"). Not all models support this — if they don't, it'll say `null`.

### The Model

```
"model": {
  "name": "flux-2",
  "variant": "flex",
  "reason": "why this model was chosen"
}
```

This tells you which AI model will work best, which version to use, and why.

### The Providers

```
"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"}
]
```

These are the services where you can actually generate the image. Each entry shows the service name, the exact model ID to use there, and the approximate cost per image. The skill doesn't recommend one over another — pick whichever works for you.

### Quality Score

```
"quality_score": {
  "overall": 8.7,
  "rating": "excellent"
}
```

A score from 0 to 10. Anything above 7 is good. Above 8 is excellent. Above 9 is exceptional. If it's below 7, the output will include suggestions for improvement.

### Warnings

```
"warnings": [
  {"category": "technical", "message": "GPT Image 1.5 limited to 1536px max"}
]
```

Heads-up about potential issues — resolution limits, missing features, or better alternatives.

### Technical Specs

```
"technical_specs": {
  "resolution": {"width": 1024, "height": 768},
  "aspect_ratio": "4:3",
  "format": "png"
}
```

The recommended settings to use when generating. If you're using an API, plug these in directly. If you're using a web interface, look for matching settings.

## 6. How It Connects to Your Workflow

Here's the big picture:

```
You describe an image
        ↓
[Image Prompt Engineer Skill]
  - Optimizes your prompt
  - Picks the best model
  - Lists providers & prices
  - Sets technical specs
        ↓
You take the output to a provider
  (Fal.ai, OpenAI, Recraft, etc.)
        ↓
Provider generates your image
```

This skill is the **middle step** — the translator between your idea and the generator. You can use its output manually (copy-paste) or programmatically (feed the JSON into an API).

## 7. For High-Volume / Batch Work

If you're generating many images (dozens or hundreds), you'll want to automate the provider step. This skill handles prompt engineering at any scale, but actually sending those prompts to a provider and managing the results is a separate concern.

For batch workflows, consider:
- Setting up API access with a provider (Fal.ai, OpenAI, etc.)
- Using a dedicated provider execution skill or script to process the JSON output
- Providers like Kie.ai offer affordable batch pricing for some models

This skill focuses on doing one thing well: engineering the best possible prompt for each image.

## 8. No API? No Problem

You don't need API access to use this skill's output. Here's how to use it with popular web interfaces:

1. **Get your optimized prompt** from this skill
2. **Copy the `positive` prompt text** (it's designed to be copy-paste friendly)
3. **Paste it into your preferred tool:**
   - **Midjourney** (Discord) — paste in the `/imagine` prompt box
   - **Leonardo.ai** — paste in the prompt field, match the recommended settings
   - **Freepik AI** — paste directly
   - **Adobe Firefly** — paste in the text box
   - **Canva AI** — paste in the Magic Media prompt
   - **ChatGPT** (with image generation) — paste as your image request
   - **Ideogram.ai** — paste in the prompt, add style codes if provided
   - **Recraft.ai** — paste in, select raster or vector as recommended

4. **Match the settings** — look for resolution, aspect ratio, and quality options in the web interface that match what the skill recommended

The prompt is written in natural English specifically so it works everywhere, not just through APIs.

## 9. Model Guide — Which Model for What

Here's a plain English guide to choosing the right model:

### "I need a realistic photo"
→ **Flux 2** — Best photorealism. Looks like a real camera took the picture. Great for product shots, portraits, real estate, food photography.

### "I need text in my image (signs, logos, titles)"
→ **Ideogram 3.0** — The king of text-in-images. If your design includes words, this is your model. Also great for branded content with specific colors.
→ **GPT Image 1.5** — Also excellent with text, especially if you want to edit the image afterward through conversation.

### "I need a logo or vector graphic"
→ **Recraft V4** — The only model that outputs real SVG vector files you can edit in Illustrator or Figma. Perfect for logos, icons, and design assets.

### "I need a huge, high-resolution image for print"
→ **Nano Banana Pro** — Goes up to 4K resolution. Great for posters, gallery prints, and anything that needs to be physically large.

### "I need something quick and cheap"
→ **Grok Imagine** — $0.02 per image, fast, and produces attractive results. Great for exploration and drafts.
→ **GPT Image 1.5 (low quality)** — $0.009 per image if you just need a quick concept.

### "I want to refine the image through conversation"
→ **GPT Image 1.5** — Unique multi-turn editing. Generate an image, then say "make the sky more orange" or "add a hat." No other model does this.

### "I need consistent style across many images"
→ **Flux 2** — Supports up to 10 reference images for character and style consistency.
→ **Ideogram 3.0** — Style codes (8-character codes) that guarantee the exact same aesthetic every time.

### "I'm making a phone wallpaper"
→ **Grok Imagine** — Has phone-specific aspect ratios (19.5:9, 20:9) that perfectly fit modern phone screens.

### "I'm designing marketing materials"
→ **Recraft V4** — Design-forward aesthetic, understands composition and visual hierarchy. Exploration mode gives you multiple directions from one prompt.

## 10. FAQ

**Q: Do I need to know which model to use?**
No. Just describe what you want and the skill will recommend the best model. You can always override its suggestion if you prefer a specific model.

**Q: Is this free?**
The skill itself is free — it just optimizes prompts. Actually generating images costs money through whichever provider you use. Prices range from $0.009 to $0.20 per image depending on model and quality.

**Q: Can I use this with Midjourney?**
Yes! Even though Midjourney has no API, you can copy the optimized prompt and paste it into Midjourney's Discord `/imagine` command. The prompts are written to work everywhere.

**Q: What if I want to generate hundreds of images?**
This skill handles prompt engineering at any scale. For the actual generation step at high volume, you'll want a separate provider execution skill or direct API integration.

**Q: Why does it sometimes suggest a different model than what I asked for?**
If you request a model that isn't ideal for your use case, the skill will note this as a warning but still optimize for your chosen model. It respects your choice.

**Q: What's a "negative prompt"?**
It's a list of things you want the AI to avoid — like "blurry, low quality, distorted." Only some models support this (mainly Ideogram 3.0). For other models, the skill handles quality control through the positive prompt instead.

**Q: Can I use this for video generation?**
No, this skill is specifically for still images. Video generation has different models and requirements.

**Q: The quality score is below 7. What should I do?**
The output will include specific suggestions for improvement. Usually it means your description needs more detail — add lighting, composition, style, or mood information.

**Q: What does "provider-agnostic" mean?**
It means the skill doesn't favor any particular service. It lists all available providers with pricing so you can choose the one that works best for you.
