Character Image Generator

intent

generate character design images, original character art, OC portraits, character sheets, and hero concept art. use this skill when a user asks for a character design, OC, character portrait, fantasy character, anime character, or original persona image. the skill is optimized for character identity, silhouette clarity, costume logic, and reusable character prompt structure.

inputs

environment variables

• IMAGE_GEN_API_KEY (required): authentication key for the WeryAI image generation gateway. obtain from your WeryAI account dashboard. never log or echo this value. can be persisted locally only via explicit npm run setup -- --persist-api-key command.

runtime dependencies

• node and npm (required)
• bun or npx (required): used to execute the generation script
• entrypoint script: {baseDir}/scripts/main.ts where {baseDir} is the directory containing this skill

external connections

• WeryAI gateway: HTTPS calls to https://api.weryai.com. requires valid IMAGE_GEN_API_KEY and network connectivity. subject to rate limits (check WeryAI docs for current limits; typically 10-60 requests per minute depending on plan). auth tokens expire; regenerate key if 401 errors persist.

user inputs (clarification order)

1. character role or archetype (e.g., mage, courier, warrior, scholar)
2. age range, gender expression, body language
3. setting (fantasy, modern, sci-fi, historical, steampunk, etc.)
4. signature outfit, props, weapons, emblems, color identity
5. composition (portrait, half-body, full-body, character sheet, turnaround)

procedure

1. readiness check: run npm run ensure-ready -- --project . --workflow <workflow> to verify node, npm, bun/npx, and IMAGE_GEN_API_KEY are present. if any dependency is missing, ask user for approval before installing. if IMAGE_GEN_API_KEY is absent, offer to configure it now (do not ask user to edit config files manually).

2. initialize default model (first run only): if no model is configured, set GEMINI_3_1_FLASH_IMAGE (Nano Banana 2) as the default. store in .image-skills/character-image-generator/config.json (project) or ~/.image-skills/character-image-generator/config.json (home).

3. clarify the character request: ask one question at a time in the order listed under "inputs" above. do not overwhelm the user. stop when you have enough detail to write a strong prompt.

4. construct the prompt using this blueprint (in order):

   • identity: role, archetype, age range, personality, faction, profession
   • look: face, hair, body language, posture, expression
   • outfit and props: signature materials, colors, weapon/tool, emblem
   • presentation: portrait, full-body, turnaround, or concept sheet
   • world feel: fantasy, cyberpunk, school life, mythology, noir, etc.

5. select style (optional): recommend only if it clarifies the request. common choices: anime, editorial, manga, photoreal. defer to user preference if stated.

6. set aspect ratio: use 3:4 or 4:5 by default for character portraits and reference art. allow user override.

7. execute generation: run the script with the finalized prompt:

   ${BUN_X} {baseDir}/scripts/main.ts \
     --prompt "<constructed prompt>" \
     --style <style> \
     --image <output-filename>.png \
     --ar <aspect-ratio> \
     -m <model-key>
   

   where ${BUN_X} is bun or npx -y bun, and <model-key> is the chosen model identifier.

8. output handling: images are written to .image-skills/character-image-generator/ (project) or ~/.image-skills/character-image-generator/ (home). display the image directly to the user; do not reply with only a filename.

9. revisions: if the user requests changes, modify only the necessary prompt direction (e.g., outfit color, pose, expression) instead of regenerating from scratch. re-run step 7 with the updated prompt.

decision points

if IMAGE_GEN_API_KEY is missing or invalid

• offer to guide the user through first-time setup via npm run setup
• do not proceed to generation until key is present and validated
• if key is invalid after setup, suggest regenerating it in the WeryAI dashboard and re-running setup
• do not store the key in plaintext unless user explicitly runs npm run setup -- --persist-api-key

if runtime dependencies are missing

• ask user for approval before installing
• recommend installing all at once: npm install (or guided setup)
• do not silently fail; report which dependency is missing

if the request is underspecified (e.g., "just a cool character")

• run through the clarification order (role, age, setting, outfit, composition) one question at a time
• use strong archetypes over generic "cool character" phrasing
• do not guess; ask the user

if the user wants variations

• change one major variable at a time (outfit, pose, expression, age, etc.)
• keep accessories and palette consistent across variants if the user is building a reusable character
• re-run generation for each variation; do not batch multiple changes

if the request includes multiple characters or a group

• only proceed if the user explicitly asks for a duo, trio, or group cast
• clarify the relationship and focal point (which character is primary)
• keep background simple so each character remains readable

if the request includes a complex background or scene

• redirect to sheet-style prompts for reference art (simple backdrop, character-focused)
• reserve scene-style prompts for narrative or story art only
• remind the user that busy backgrounds can obscure costume and silhouette

if rate limits are hit

• wait the specified backoff duration (typically 60 seconds to 5 minutes depending on WeryAI plan)
• inform the user of the wait and retry automatically or ask for permission
• do not retry immediately; respect rate limit headers

if network timeout or connectivity fails

• retry up to 2 times with exponential backoff (5 seconds, then 10 seconds)
• if persistent, inform the user and check WeryAI status page
• do not lose the prompt; ask user if they want to retry or adjust the request

if the generated image does not match the prompt

• check the prompt for ambiguity or competing directives
• simplify the prompt and re-run
• if model-specific, try a different model (if available) and note the difference

output contract

success state: a single PNG image file, written to .image-skills/character-image-generator/output/ or user-specified location, displaying the requested character design with:

• clear silhouette and readable costume details
• consistent color identity and material suggestions
• appropriate pose and expression for the archetype
• background simple enough that character remains dominant (unless scene art was explicitly requested)

metadata: the script logs the following to stdout:

• model used (e.g., GEMINI_3_1_FLASH_IMAGE)
• aspect ratio applied (e.g., 3:4)
• style preset applied (if any)
• output file path
• generation time (in seconds)

file locations:

• project-level config: .image-skills/character-image-generator/config.json
• home-level config: ~/.image-skills/character-image-generator/config.json
• generated images: .image-skills/character-image-generator/ or user-specified path

edge cases handled:

• empty result set: if WeryAI returns no image (API error), the script exits with a non-zero code and logs the error. do not display a broken image.
• auth expiry: if IMAGE_GEN_API_KEY is revoked or expired, the API returns 401. instruct user to regenerate the key and re-run setup.
• invalid aspect ratio: if user specifies a ratio not supported by the model, the script defaults to 3:4 and logs a warning.
• local file path in prompt: the skill rejects data: URLs and local file paths (e.g., /home/user/image.png). reference images must be public HTTPS URLs.

outcome signal

the user knows the skill worked when:

• the generated character image appears directly in the chat or output window
• the image matches the character archetype, outfit, color palette, and pose described in the prompt
• the silhouette is clear and the costume details are readable at a glance
• the user can request revisions by asking for minor changes (e.g., "give her a different hair color") and the next image reflects only that change
• no error messages appear; the generation completes without timeouts or auth failures