moonlight-lupin/agent-skills/image-studio

Image Studio

Turn an idea into a finished image through three deliberate stages — brainstorm → prototype cheaply → produce the final — using fal.ai. The point of the staging is cost and control: iterate cheaply on a fast model, lock the concept with the user, then spend on a quality model only once, on the agreed image.

This skill generates files locally for the user to review and use. It never posts, publishes, or sends anything as final brand collateral.

Scope and routing

Use this skill only when all of the following are true:

1. The task is generative imagery or image editing, not layout/design automation, charting,

dashboarding, flowcharting, or slide/deck production.

1. The user is comfortable with fal.ai egress and paid API usage.
2. The local helper workflow is available or the user is asking you to prepare the prompt/brief for

that workflow.

Do not use this skill for:

• Canva templates, PowerPoint decks, branded presentation layouts, data charts, dashboards,

flowcharts, architecture diagrams, or process diagrams.

• Video generation.
• Confidential or sensitive image/document processing.
• Any host environment where a native image-generation/editing tool is explicitly mandated.

Three modes — choose first

The workflow depends on whether you are creating an image, changing an existing one, or cleaning up an existing one — they do not use the same steps:

• Path A · Create from scratch (no source image). The composition is unknown, so prototype

cheaply to explore it, then finalise at quality — use Stage 1 → 2 → 3 below.

• Path B · Edit / overlay on an existing image (populate a room with people, restyle a photo,

add or remove an element). The composition is already fixed by the source photo, so a cheap prototype only adds drift and artefacts that do not predict the quality result — skip it. Brainstorm and confirm the prompt (Stage 1), then quality-edit the original directly (Stage 3). For cost-sensitive multi-iteration work, iterate on the same-family fal-ai/nano-banana/edit (a faithful preview) rather than on Kontext dev. The "prototype" is the agreed prompt, not an image.

• Path C · Clean up / enhance an existing photo (turn an amateur/phone shot professional — fix

flare, reflections, white balance, exposure, perspective/warp, noise, clutter). Same mechanics as Path B (no prototype; quality-edit the original in one comprehensive pass), but the intent is faithful correction, not change — build the prompt from references/cleanup-checklist.md and keep every real feature exactly. Works for any subject — interiors, portraits, products, food, landscapes. One checklist-driven pass usually suffices. See the Clean-up section below.

Stages 1–3 describe Path A in full; Paths B and C reuse Stage 1 (brainstorm/confirm) then go straight to Stage 3 (quality-edit the original), skipping the Stage-2 prototype.

Before you start — egress and preflight

Generating an image sends the prompt to fal.ai. Editing, upscaling, or background removal also sends the image you provide to fal.ai. fal.ai is a third-party US service, and result images are downloaded from its CDN. That is external data egress.

Before any API call:

1. Confirm the task is within scope.
2. Confirm explicit user go-ahead for fal.ai egress and paid API usage before the first generation in

a session.

1. Confirm explicit user go-ahead again before the costlier Stage-3 production run.
2. Check that scripts/falgen.py exists, dependencies are installed, FAL_KEY is set, and the working

directory is writable.

1. For edits, upscales, and background removal, use only non-confidential, non-sensitive images that

the user has rights to process through fal.ai.

1. Use the exact output paths printed by falgen.py; do not infer filenames from examples.

Never feed confidential or sensitive imagery or documents to fal.ai — e.g. a person's photo, confidential report, deal materials, financial documents, investor materials, tenant materials, valuation materials, or anything under NDA. If the user asks to edit something sensitive, stop and flag the egress issue rather than uploading it.

Brainstorming in Stage 1 is pure chat and has no egress, so you can always draft the prompt first and confirm the send afterwards.

Setup needed: a fal.ai account with billing, and the FAL_KEY — either the environment variable, or just saved in a text file in the working folder (any filename, e.g. fal key.txt). The helper finds the key automatically — env var first, then any small text file in the working folder (a FAL_KEY=your-key line, or a raw key matching fal's id:secret shape), then the home dir (only files whose name mentions fal/key/api/env, and only an explicit FAL_KEY=… line — bare tokens are never taken from home, so other services' credentials can't be picked up). So don't ask the user for a key before checking; only prompt if none is found. It uses the fal-client package (pip install fal-client requests). If no key is found the helper fails with a clear message — generation cannot proceed without it, but Stage 1 still works. (Keep any key file local; never commit it.)

Stage 1 — Brainstorm the prompt (no API call)

Good output starts with a good prompt, so invest here before spending anything. Interview the user and build a structured prompt brief covering:

• Subject — what is in the image, concretely.
• Style / medium — photoreal, 3D render, flat illustration, line art, watercolour, etc.
• Composition — framing, focal point, layout, and where any text or negative space sits.
• Lighting / mood — soft, dramatic, corporate-clean, warm, moody.
• Colour palette — whatever the user wants, without confidential detail.
• Aspect ratio — anchor to the destination: 16:9 deck/hero, 1:1 or 4:5 social, 9:16 story,

2:3/3:4 portrait, or custom banner proportions.

• Quality modifiers & negatives — e.g. "high detail, sharp focus"; "no text, no watermark, no

extra fingers".

Offer two or three distinct prompt directions rather than one, so the user can react to options. Save the agreed brief to _workings/ (for example, _workings/prompt-brief_[slug].md) so the run is auditable. Keep prompts free of confidential detail.

For Paths B and C this is the step that replaces prototyping, so confirm the prompt with the user before the first paid call. When the subject is people or an overlay onto a real scene, two craft notes:

• Name the action, not the mood. "Sitting smiling" reads stiff and posed. Specify genuine

interaction — "mid-conversation, one gesturing, two looking at each other, one showing a laptop screen to a friend" — so people relate to each other, not the camera.

• Protect faces. Distant/small faces deform easily — prefer fewer, larger people, add "clear,

natural faces and hands", and re-edit just a bad region rather than re-rolling the whole image.

Stage 1.5 — Prompt-out contract (check before Stage 2)

Before handing any prompt direction to Stage 2, verify each line:

• Every in-image text string appears verbatim as FINAL copy, in its target language, with role and

placement stated (title / detail / footnote) — never "the title" or a placeholder, never an invented name or logo.

• Negatives fit the image: when text is required content, no "no text" negative survives from the

generic examples; state any intentionally absent content instead.

• No instruction-like phrasing inside the image description; the prompt describes only the visible

image.

• A card / poster / design direction states that the design fills the frame, unless mockup framing

is wanted.

• The user's subjects, counts, exclusions and intended visible wording are preserved exactly.

If any line fails, fix the prompt directions before Stage 2.

Stage 2 — Prototype cheaply and iterate

Generate with a cheap, fast text-to-image model so iteration is inexpensive, then refine on the user's feedback until they approve a prototype.

First render — text-to-image with FLUX schnell:

python scripts/falgen.py generate \
  --prompt "[the agreed prompt]" \
  --aspect 16:9 --num 2 \
  --run-log _workings/run-log_[slug].md \
  --out-dir _workings --name image_[slug]_v1

--num 2 gives the user a couple of variations to choose from. The helper may save multiple files such as image_[slug]_v1_1.png and image_[slug]_v1_2.png; always use the exact saved paths printed by the helper.

On feedback, choose the cheaper move:

• Concept or big composition change → refine the prompt wording and re-run generate as the next

version (--name image_[slug]_v2, etc.).

• Targeted tweak to a chosen image — for example, "make the sky warmer", "remove the building on

the left", or "add more negative space top-right" → use edit.

The Stage-2 default editor is FLUX Kontext [dev] (fal-ai/flux-kontext/dev). It is a cheap instruction editor billed per compute-second; fal does not return exact runtime locally, so the helper flags the cost as time-billed and the fal dashboard remains the source of truth. Kontext preserves the input image's dimensions and changes only what you name.

python scripts/falgen.py edit \
  --prompt "make the sky warmer and add negative space top-right" \
  --image _workings/[actual_saved_prototype_path].png \
  --run-log _workings/run-log_[slug].md \
  --out-dir _workings --name image_[slug]_v3

Do not pass --aspect to Kontext edits; Kontext keeps the source dimensions. Kontext accepts a single image. If multiple reference images are required, use a model that supports image_urls, such as fal-ai/nano-banana/edit, and confirm the cost trade-off.

Save every iteration to _workings/ with an incrementing version so nothing is lost. Loop until the user says "that's the one".

Why two paths: a prompt re-roll explores fresh compositions; an edit holds the composition the user

already likes and changes only what they named. Pick the one that matches the feedback.

Stage 3 — Produce the final

Once the user approves a prototype, confirm the go-ahead again. This is the main spend.

Render the agreed concept at quality and at the resolution the user actually needs. Usually, getting the final at target size removes the need for a separate upscale.

Confirm the resolution — 2K or 4K? It changes the price, so ask:

• 2K (sensible default). Good for on-screen and in-hand use — decks, social, web, email, digital

PDFs — and standard print to ~A4. Not ideal for large-format print read up close, or heavy crop-and-enlarge.

• 4K — Nano Banana Pro bills this at 2× the base (see references/fal-models.md). Good for

large-format/close-viewed print (posters, banners, exhibition panels) or future-proofing a reusable hero. Not worth it for screen/social, which downscale anyway.

Pass it via --arg resolution=2K (or 4K); the helper reflects the 4K surcharge in the reported cost.

1. Quality render at target resolution — edit the approved prototype with Nano Banana Pro

(fal-ai/nano-banana-pro/edit, flat per image) to stay faithful to it, asking for the output size up front via resolution (up to 4K):