# Image Generation > Generate and refine brand-consistent images from libraries, references, and prior candidates. Use before calling image-generation or refinement actions. - Skill: `builderio/image-generation` (Agent Skill) - Install (CLI): `npx skillmds@latest add builderio/image-generation` - Raw SKILL.md: https://api.skillmd.com/api/skills/builderio/image-generation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Builder.io (https://skillmd.com/u/builderio) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/builderio/image-generation --- # 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 `slotId`s 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//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 `` 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 `runId`s, `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.