ad-designer

# Ad Designer

Generate marketing ad images from campaign-planner creative briefs. Wrap nano-banana-pro with brand-aware prompt construction, aspect ratio handling, and a self-review loop that catches quality issues before marking images final.

## Roles

- **Ad Designer** (this skill) — sole executor
- **nano-banana-pro** — image generation engine (upstream dependency)
- **campaign-planner** — upstream source of creative briefs
- **brand-bible-builder** — upstream source of brand visual identity

---

## Prerequisites

Verify before starting:

```bash
command -v uv
test -n "$GEMINI_API_KEY"
test -f ~/.codex/skills/nano-banana-pro/scripts/generate_image.py
```

If `uv` is missing: tell the user to install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`.
If `GEMINI_API_KEY` is unset: tell the user to export it from Google AI Studio.
If the script is missing: tell the user the nano-banana-pro skill must be installed first.

---

## Step 1: Collect Inputs

Identify which inputs are present in the conversation or filesystem:

| Input | Source | Where to find it |
|-------|--------|-----------------|
| Creative brief(s) | campaign-planner skill | `/tmp/marketing/campaigns/<brand>-campaign-plan.json` → `ad_creatives[]` array, or inline in conversation |
| Brand bible | brand-bible-builder skill | `/tmp/marketing/brands/<brand>/brand-bible.md` or inline |
| Aspect ratio | User or brief | Defaults to 1:1 if not specified |
| Resolution mode | User | Defaults to draft (1K) unless user says "final" or "4K" |

If the creative brief is missing, ask:

> "I need a creative brief to generate the ad. Run `/campaign-planner` first, or paste the brief details: headline, visual direction, CTA, and target audience."

If the brand bible is missing, proceed with neutral visual defaults — note this in the output and recommend running `/brand-bible-builder` for on-brand results.

---

## Step 2: Read Brand Bible Visual Identity

Open the brand bible and extract these fields into a working reference:

- **Primary colors** — hex codes or descriptors (e.g. `#1A2E5A deep navy`, `#F5A623 amber`)
- **Secondary / accent colors** — supporting palette
- **Font style** — serif vs sans-serif, weight, mood descriptor (e.g. "bold geometric sans", "light editorial serif")
- **Imagery style** — photography vs illustration, lifestyle vs product-only, color grading mood (warm/cool/muted/vibrant)
- **Layout pattern** — minimal and clean vs content-dense, whitespace-heavy vs layered
- **Tone** — formal, casual, bold, playful, premium, approachable

Keep this as a 6-field internal reference. Do not show it to the user. Use it when constructing prompts in Step 3.

---

## Step 3: Construct Image Generation Prompt

Apply these rules every time. They are non-negotiable.

### Core Rules (from best-practice image generation)

**Rule 1 — Less is more.** Short, focused prompts outperform long descriptive ones. Target 15–30 words for the visual description. Cut adjectives that repeat the same idea.

**Rule 2 — No logos, brand names, or company names.** Never include the brand name, product name, logo description, or any trademark in the prompt. The generation engine hallucinates these badly and they must be added in post-production.

**Rule 3 — Only include text that is explicitly specified.** If the brief specifies a headline to appear in the image, include it exactly as written — no paraphrasing. If no text is specified, do not add any text to the prompt. Do not include CTAs, taglines, or copy unless the brief explicitly says to render text.

**Rule 4 — Describe emotion and composition, not data.** Instead of "a woman saving money on her bills," write "confident woman, bright home office, warm morning light, relaxed expression." The emotion communicates the message; the model handles the rest.

**Rule 5 — Translate brand colors without naming the brand.** Convert hex codes to descriptors: `#1A2E5A` → "deep navy", `#F5A623` → "warm amber". Use these color words in the prompt naturally.

### Prompt Construction Formula

Assemble the prompt in this order:

```
[SUBJECT] — who or what is the focal element
[SETTING] — environment or background context
[MOOD / EMOTION] — feeling the image should evoke
[COMPOSITION] — framing, shot type, perspective
[LIGHTING] — quality and direction of light
[COLOR PALETTE] — 2–3 colors derived from brand bible
[STYLE] — photography/illustration style from brand bible
[AVOID] — explicit exclusions (text, logos, clutter, etc.)
```

Do not use all 8 fields every time. Use only those relevant to the brief. A 5-field prompt is often stronger than an 8-field one.

### Example Construction

Brief input:
```
headline: "Finally, sleep that works"
visual_direction: "Woman waking up refreshed, natural light bedroom"
cta: "Try free tonight"
target_persona: "Aisha, 28, KL, stressed professional"
```

Brand bible: warm coral `#E8735A`, off-white `#FAF7F2`, editorial sans-serif, warm and minimal photography style.

Constructed prompt:
```
Young woman waking up peacefully, sunlit minimalist bedroom, linen textures,
warm coral and off-white tones, soft morning light through sheer curtains,
close-up on relaxed expression, warm editorial photography style
```

What was excluded: brand name, CTA text, product name, headline text (no text was specified for visual rendering).

---

## Step 4: Select Aspect Ratio

Map the brief's platform or format to the correct ratio flag and pixel dimensions:

| Platform / Format | Ratio | Pixel Dimensions | Use Case |
|-------------------|-------|-----------------|----------|
| Instagram / Facebook Feed | 1:1 | 1080 × 1080 | Square feed post |
| Instagram Story / Reel | 9:16 | 1080 × 1920 | Full-screen vertical |
| Facebook Feed (portrait) | 4:5 | 1080 × 1350 | Taller feed post, more screen area |
| YouTube / LinkedIn Cover | 16:9 | 1920 × 1080 | Landscape / banner |

If the brief does not specify a platform, default to 1:1.

For carousel ads: generate all cards at the same ratio. Use 1:1 unless the brief specifies otherwise.

Pass the ratio to the script via `--resolution`. The nano-banana-pro script handles internal sizing. Generate at 1K for drafts, 4K for finals.

---

## Step 5: Generate Images

Create the output directory:

```bash
mkdir -p /tmp/marketing/assets/images
```

### Single image generation

Use this command pattern. Always use absolute path for the script.

```bash
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py \
  --prompt "<constructed prompt>" \
  --filename "/tmp/marketing/assets/images/<timestamp>-<brief-id>-draft.png" \
  --resolution 1K
```

Filename format: `yyyy-mm-dd-hh-mm-ss-<brief-id>-draft.png`
- `brief-id`: lowercase kebab-case derived from the brief headline (e.g. `finally-sleep-works`)
- Use current date/time for timestamp

### Draft-first workflow

Always follow this sequence:

1. **Draft at 1K** — generate first at 1K for fast feedback. Present to user.
2. **Iterate** — if issues found in self-review (Step 6), adjust prompt and regenerate at 1K. Max 3 attempts.
3. **Final at 4K** — only after user approves the draft or after self-review passes. Change filename suffix from `-draft` to `-final`, set `--resolution 4K`.

### Carousel ads

Generate each card as a separate image. Naming convention:
```
yyyy-mm-dd-hh-mm-ss-<brief-id>-card-01-draft.png
yyyy-mm-dd-hh-mm-ss-<brief-id>-card-02-draft.png
```

Ensure visual consistency across cards:
- Use the same color palette descriptor in every card's prompt
- Use the same style descriptor in every card's prompt
- Use the same lighting descriptor in every card's prompt
- Vary only the subject and composition per card

---

## Step 6: Self-Review Loop (CRITICAL)

After generating each image, perform a structured self-review before presenting to the user. Do not skip this step.

Run through this checklist for every generated image:

| Check | Pass Condition | Fail Action |
|-------|---------------|-------------|
| Text accuracy | Any specified text appears correctly and is readable | Simplify prompt; add explicit text instruction |
| No hallucinated logos | No brand marks, wordmarks, icons, or watermarks visible | Add "no logos, no text, no watermarks" to avoid clause |
| No hallucinated brand names | No company names or product names rendered as text | Add "no brand names, no product names" to avoid clause |
| Aspect ratio | Matches requested format | Re-run with correct ratio flag |
| Color alignment | Dominant colors match brand palette intent | Strengthen color descriptors in prompt |
| Overall quality | Image is coherent, professional, on-brief | Rebuild prompt from scratch using simpler structure |

### Fail response

If any check fails:

1. Identify the specific failure from the table above.
2. Apply the corresponding fail action to the prompt.
3. Regenerate at 1K.
4. Re-run the self-review checklist on the new image.
5. Stop after 3 total attempts. If still failing on attempt 3, present the best result to the user with a note explaining what the issue is and what was tried.

Do not present a failing image silently. Always tell the user what was wrong and what fix was applied.

---

## Step 7: HITL — Present for User Review

After self-review passes (or after 3 attempts), present the results:

```
Ad image(s) generated for: [brief headline]

Draft(s) saved to /tmp/marketing/assets/images/:
  [timestamp]-[brief-id]-draft.png   ← [ratio] | 1K

Self-review: [PASS / notes on any issues found and fixed]

Review the image and reply with one of:
  A) Approve → I'll upscale to 4K final
  B) Adjust → describe what to change
  C) Skip → move to next brief
```

Wait for the user's response before generating the 4K final or moving to the next brief.

If the user says "adjust" or describes changes:
- Apply the change to the prompt (keep changes minimal — one diff at a time)
- Regenerate at 1K
- Re-run self-review
- Present again

If the user approves:
- Regenerate at 4K with `-final` filename suffix
- Confirm: "Final saved: `/tmp/marketing/assets/images/[filename]-final.png`"

---

## Step 8: Process Multiple Briefs

If the input contains multiple briefs (e.g. from a campaign-planner JSON with 3–5 image ad entries), process them sequentially. Complete the full cycle (generate → self-review → HITL approval → final) for each brief before moving to the next.

After all briefs are processed, present a summary:

```
All ad images complete.

Generated:
  /tmp/marketing/assets/images/[file-1]-final.png   [ratio]
  /tmp/marketing/assets/images/[file-2]-final.png   [ratio]
  /tmp/marketing/assets/images/[file-3]-final.png   [ratio]

Next step: run /meta-ads-publisher to upload these to your ad account,
or /campaign-planner to review the full campaign.
```

---

## Error Handling

| Error | Action |
|-------|--------|
| `Error: No API key provided.` | Tell user to run `export GEMINI_API_KEY=<key>` and retry |
| `Error loading input image:` | Verify the `--input-image` path exists; fix path and retry |
| `quota / 403 / permission` API error | Wrong key or quota exceeded; ask user to check Google AI Studio quota |
| Script not found at `~/.codex/skills/...` | nano-banana-pro skill is not installed; tell user to install it from ClawHub |
| `uv: command not found` | Run `curl -LsSf https://astral.sh/uv/install.sh | sh` then retry |
| Image generation returns blank/empty | Prompt may be too restrictive; remove avoid clauses and simplify to subject + style only |

---

## File Paths Reference

```
/tmp/marketing/
├── assets/
│   └── images/
│       ├── yyyy-mm-dd-hh-mm-ss-<brief-id>-draft.png    ← draft outputs
│       └── yyyy-mm-dd-hh-mm-ss-<brief-id>-final.png    ← approved 4K finals
├── brands/<brand>/
│   └── brand-bible.md                                   ← brand visual reference
└── campaigns/
    └── <brand>-campaign-plan.json                       ← input brief source
```