image-generation

name	image-generation
description	Generate and refine brand-consistent images from libraries, references, and prior candidates. Use before calling image-generation or refinement actions.

Image Generation

Use this skill before calling generate-image, generate-image-batch, or refine-image.

Prompt contract

Treat references as evidence, not decoration. The prompt should explain the asset's job, subject, framing, medium, lighting, palette, exact text policy, and what must not change. Keep the active library or preset's style brief and the caller's design-system constraints authoritative; Impeccable-style composition guidance may improve the result but must not replace them.

Before generating, decide whether the slot needs a produced image, a direct reuse of an approved asset, or a semantic UI/icon/diagram owned by the caller. Do not use image generation to paper over missing product facts, customer evidence, screenshots, or exact logos.

Rules

• Start from composer @ mentions when the user tags generation inputs. brand-kit references map to libraryId, preset references map to presetId, and media-type references choose image generation versus video generation. Call view-screen when the user says "this library" or "this image" and you need fresh IDs. The image model may default from the composer image-model picker.
• A tagged @preset (presetId) owns aspectRatio, imageSize, model, tier, and category. When a preset is set, do NOT pass those args yourself — leave them out so the preset's saved values are used. You cannot see the preset's settings from the presetId, so passing your own guess silently overrides the preset (this is the usual cause of a preset's aspect ratio being ignored). Pass one of these args alongside a preset ONLY when the user explicitly asks for a value that differs from the preset. When there is no preset, set them explicitly or rely on the action schema defaults.
• Use category-tagged references. Blog heroes should prefer hero; diagrams should prefer diagram; product imagery should include product and logo references.
• Imported external images with status: "reference" are valid generation inputs. Use their returned asset IDs in preset reference fills or reference boards the same way you would use uploaded reference assets.
• Keep reference sets small and deterministic. Prefer anchors listed in assetLibraries.settings.canonicalStyleAssetIds and assets marked assets.metadata.isStyleAnchor before sampling other relevant references.
• Honor library custom instructions. They are persistent prompt guidance and should be updated when the user wants durable generation behavior.
• Generate the selected candidate count for open-ended requests, usually 2-4. Use generate-image-batch with stable slotIds so the shared generation tray can show live slots.
• generate-image and generate-image-batch are synchronous for images. One batch call should produce the requested candidates and return compact asset summaries with IDs and URLs; do not follow it with get-generation-run, refresh-generation-run, or more generation unless the user asks for another direction or the returned slot has ok: false.
• Use get-asset when full asset details are needed. Use get-audit-run or list-audit-runs for the prompt, compiled prompt, references, and generation settings.
• For repeatable deliverables, honor a template @mention as templateId or call list-templates when choosing one. Pass the template through generate-image, generate-image-batch, refine-image, or rerun-generation-run.
• For designer handoff, preserve sessionId and call update-generation-session after each new candidate so the active asset, feedback, and run lineage stay resumable.
• Show previews in chat. In Assets, use /asset/<assetId>/embed; from another app, preserve the returned preview/download URLs exactly.
• Iterate with refine-image --assetId. Use edit-image for targeted edits and restyle-image when the user wants to preserve a subject image while applying library style. Pass subjectAssetId, styleStrength, and tier when they matter.
• Use quality tier values intentionally: fast for exploration, best for final/high-value output, and auto when there is no clear preference.
• Cross-agent callers must pass source: "a2a" and callerAppId to generate-image-batch / refine-image. The design team uses the audit log to review quality by app, library, model, prompt, and lineage.

Composer Mentions And Tagged Templates

• Composer @ mentions are the source of generation inputs. Map brand-kit references to libraryId, template references to templateId, and media-type references to choosing image (generate-image / generate-image-batch) or video (generate-video) generation.
• The current library view auto-tags its brand kit as a visible removable chip, and the template editor auto-tags an associated template with its brand kit.
• The image model is the only remaining composer-side default; the image-model picker writes imageGenerationModel, which image generation actions may use when model is omitted.
• When a template is tagged, the server embeds that template's aesthetics and creative philosophy (brand style brief, prompt template, text/logo policy, output format) into your message inside a <tagged-templates> block. Study and internalize that brief before you generate — let it drive composition, mood, lighting, and subject — then pass the templateId to generate-image / generate-image-batch so the saved format/model/tier/logo apply automatically. Do not restate those as ad-hoc args.

Template-first Generation

• Image requests without a tagged template are template-first: the user may not know templates exist. Compare the request against each template's title, description, and category, and if one matches the use case (e.g. "livestream poster" -> a Livestream Announcement template), generate with its templateId instead of ad-hoc settings. Only generate without a template when nothing plausibly matches.
• Before any ad-hoc generation for a brand kit, call list-templates and scan titles/descriptions/categories for a use-case match. A template encodes the designer's format, model, layout, and reference board; using it is always better than improvising.
• If one template clearly matches: use its templateId; do not restate its saved aspect ratio/size/model/tier. If several plausibly match: pick the best and state which one you used; do not ask the user to choose.
• Match named people/products/backdrops in the request to the template's reference board entry labels in settings.presetReferences. Fill required variable entries via presetReferenceFills: search the library for assets of those people first; ask the user for photos only when none exist. Never skip a required entry.
• Route exact visible copy such as event titles, dates, and times to embeddedText per the existing text rules; keep the creative direction in prompt.
• For exact visible copy inside a generated image, pass embeddedText and optional textPlacement to generate-image or each generate-image-batch slot. Keep the general prompt for creative direction; the structured text fields are what allow the pipeline to render copy instead of suppressing it.
• If nothing matches: generate ad-hoc, say that no template fit, and mention a template could be created for this recurring use case. The deprecated *-generation-preset actions remain aliases for existing agent threads.

Prompting

• Treat references as evidence, not decoration.
• Let the server choose references unless the user named exact assets. Automatic generation uses up to 6 relevant current references, seeded by canonical style anchors; explicit referenceAssetIds are preserved.
• Template reference boards live on tagged templates as named entries such as a usual host, product, backdrop, style sample, or per-event speaker. Fixed entries attach automatically. Variable entries may be replaced for a run with presetReferenceFills; each fill REPLACES that entry's pinned images rather than appending. Required variable entries block generation until you provide at least one image.
• When a tagged template brief names required variable references, collect the needed images from the user's attachments or the library and pass presetReferenceFills: [{ referenceId, assetIds }] to generate-image or generate-image-batch. Board images are additive to brand style references. User-uploaded per-event people/photos should be uploaded as content images (subject intent/role), not as reusable brand style references.
• If a collection's style feels underspecified, call analyze-collection-style and use its vision brand analysis for palette, composition, lighting, subject treatment, typography policy, and constraints.
• Compile the style into a short brief: palette, composition, lighting, medium, typography policy, subject framing, custom instructions, and constraints.
• For short vague prompts, enhance conservatively with library context while preserving the user's exact text as originalPrompt.
• Avoid visible text unless explicitly requested. For diagrams, ask for clear hierarchy, exact label placement, consistent line weights, and whitespace.
• For exact logos, use the uploaded canonical logo path. The generation prompt should leave a clean area; the server composites the logo after generation.
• Do not describe brand QA scoring or best-of-N selection as available yet.

Completion

After generation, reply with asset IDs and previews. Ask whether to save, iterate, or produce another direction.

When the user says a designer should pick up the work, create a generation session with create-generation-session, including the active assetId, relevant runIds, presetId, and the feedback summary. Use prepare-generation-session-continuation to open a new chat with the handoff context preloaded.

Every generation is audit logged automatically. When a reviewer asks how images are performing, use navigate --view audit, list-audit-runs, or get-audit-run.

Use rerun-generation-run to rerun the original prompt and settings from an older generation against the latest library style brief, custom instructions, collection data, and deterministic references.