Prompt Writing

Always write generation prompt text in English, even when the user communicates in another language. The surrounding conversation may remain in the user's language, but every prompt shown to the user or sent to Astria must be English.

Before writing a prompt, use the connected MCP tools (see astria-api):

• list_prompts with limit: "20" — their recent prompts, to learn their style and parameters.
• list_templates — their packs. If the request is about a specific subject (e.g. a shirt), find a pack whose main_class_name matches and inspect its template prompts using list_prompts and pack_id.
• list_references — their references/tunes. If any match what they want to generate, reference it in the prompt via <model_type:id:1> name syntax (see the astria-api skill).

Do not send the user off to browse packs or tunes themselves — query with the tools and bring concrete suggestions back to them. When offering choices, your ask-user question tool (AskUserQuestion in Claude Code, ask_user in the Astria chat agent) with image thumbnails helps them pick.

If no tune matches the request, follow intent:

• For headshots / models / avatars, do NOT ask for a reference first. Propose ready-to-generate prompt options and trait options (look, age range, styling, framing, lighting), then confirm generation settings.
• For product or person-specific identity requests where likeness matters, ask the user to provide a reference image (upload it as a tune using create_reference and an accessible HTTPS image URL, or drag it into the prompt box in the web app).
• Do not suggest web search for this flow.

For a prompt-writing request, show the prompt for review before generating. For an explicit generation request, use the requested image count and settings; clarify only settings that materially affect the result and are missing. Submit through generate_images with a fresh idempotency key (see astria-api).

Types of request

1. E-commerce / product shots — reference tunes to create a new image.
2. Image editing — pass generate_images with input_image: "<HTTPS URL>" to modify an existing image (change background, change style, add/remove objects).
3. Upscaling — generate_images with text: "Recreate this image in 4K" and an input_image HTTPS URL; select a model supporting 4K from list_models. If the image has prominent text labels, mention them in the prompt so they survive the upscale.

Prompt Writing Guide

Use the default image model and model_selection_guidance returned by list_models, unless the user explicitly requests another model or the specialized skill requires one. Avoid legacy Flux.1 for image generation and editing unless the user explicitly requests Flux.1. Do not infer a model choice from a reference's base model, a previous generation, or inherited composer settings. This also applies when editing an existing Flux.1 draft: use the catalog default, preserve the subject references, and briefly explain the model change. A Flux-trained avatar is a subject reference, not a reason to generate with Flux.1. No need to ask the user about model type unless they explicitly mention another one or ask for a recommendation.

Default intent mapping

If the user asks to create "models", "avatars", or "headshots", interpret this as a request for realistic, unique face headshots on a clean white studio background:

• Do not use any reference tune for this request type.
• Keep framing as a face headshot (not full body), white #fff studio backdrop, studio lighting.
• Proactively offer prompt/trait choices with an ask-user question instead of asking for references.
• Treat nationality words ("israeli", "french", "japanese") as styling/trait guidance for facial features and casting diversity, not as a request for references.
• Do NOT suggest fashion, lookbook, lifestyle, full-body, or outfit-led prompts for this request type unless the user explicitly asks for those.

See the avatar skill for the detailed face-trait template.

Interaction rule (strict)

Never ask a question and suggest prompt text in the same response.

• If you use the ask-user question tool, return only questions/options in that turn.
• After the user answers, return the prompt suggestion(s) in the next turn.

References

For a reference tune always use <model_type:tune.id:1> tune.name to reference the trained subject:

• portrait of <faceid:123:1> woman in a garden wearing <faceid:124:1> dress — CORRECT
• portrait of John in a garden — WRONG (the model doesn't know "John")

The trailing :1 is a fixed part of the token syntax — it is NOT a weight or strength. Always write :1; never vary it, and never tell a user to change it.

Reviewing bad results

If the user says results are bad, figure out what went wrong:

1. Inspect each reference's orig_images (get_reference with id) and check the name matches the image content. If name=woman but the image is a full-body shot including clothes or a hat, tell the user to re-crop the training images on that tune's page (/tunes/<id> → "training images" → crop tool).
2. The name must represent the main subject. "jewelry" is a poor name — it should be "ring" or "necklace" depending on the subject. If a tune named "jewelry" holds a ring, suggest renaming it to ring and retraining on the tune's page. Reference updates are currently CLI/UI-only.
3. Distorted or competing faces (e.g. a LoRA and a FaceID of the same person in one prompt): turn on "Inpaint faces" in the composer settings, or remove the extra face reference (✕ on its chip). Do NOT suggest adjusting the numbers inside reference tokens — there is no reference-weight control.

Key parameters

Tips for better results

• Include background descriptions: "clean white studio", "blurred urban street", "autumn forest".
• For product shots, describe the surface and arrangement.

Keeping the background identical across generations

Gemini / Nano Banana does not hold a backdrop exactly from one generation to the next — the shade and brightness of a studio background drift even when a background reference is attached. Wording cannot fix this; the reliable fix is the post-processing flag, appended to the prompt text:

<faceid:123:1> woman in a studio --background_color #f2f0ed

--background_color #RRGGBB recolors the detected background to that exact hex after generation, so a whole catalog lands on the same backdrop. It runs on Gemini / Nano Banana, partner models and Kontext — not on Flux. In the web app it is the "Background color" row in the composer's options cog.

Two related mistakes to check when a user reports a drifting background:

• Text like "match the provided background reference" with no background reference actually attached — the model then invents a backdrop every run. Attach it as a reference (<faceid:ID:1> background) or describe the exact colour instead.
• Five or six references stacked in one prompt (subject + outfit + shoes + hat
  • bag + background). They compete, and the background gives way first — keep the essentials and add accessories in a second pass.

Fashion and garments

1. Always work with a consistent face reference. If the user has none, suggest a faceid tune from the public gallery (list_references with gallery: true, model_type: "faceid", limit: "200") or generate a face first (no reference) and convert one of those outputs into a tune using create_reference and an accessible HTTPS image URL.
2. Figure out the intent — a lookbook (e.g. prompt look book plain white background #fff) or a campaign shot. Campaign example: A direct flash paparazzi style shot of <faceid:3904080:1> woman moving through a crowded bar. She looks straight into the lens with an intense expression. She wears the <faceid:3907553:1> dress and the <faceid:3907242:1> bag on her shoulder. The background is dark and out of focus. High contrast, sharp flash.