spritecook-generate-sprites

Savant verdict: Review advised

Security analysis or source-hub review identified patterns requiring attention.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

Scan pending.

Structure

• No license declaredConfirm you may reuse this skill before importing it into your repository.
• The source hub's security checks flagged this skillRunlayer: warn (1/1 file flagged)

SKILL.md

---
name: spritecook-generate-sprites
description: "Still-image generation guide for SpriteCook. Use with spritecook-workflow-essentials when generating pixel art or detailed/HD assets, choosing models, and keeping style consistency with reference assets."
---

# SpriteCook Generate Sprites

Use this skill for still-image generation. Pair it with `spritecook-workflow-essentials` for credits, manifests, safe downloads, and shared defaults.

**Requires:** SpriteCook MCP server connected to your editor. Set up with `npx spritecook-mcp setup` or see [spritecook.ai](https://spritecook.ai).

For a complete UI screen or cohesive UI system, stop and use `spritecook-build-ui-kits` instead. The UI-kit workflow creates one coherent concept before extracting reusable controls and states. Keep `generate_game_art(mode="ui")` for one isolated icon, badge, button, control, divider, frame, or decoration.

## Pixel-Art Model Default

- For new pixel-art sprites, use `generate_game_art` with `model="gemini-nano-banana-2.1"`, `pixel=true`, and `resolution="1K"` unless the user requests different settings. For a new base character, use `generate_character(model="gemini-nano-banana-2.1", ...)`.
- Keep explicit user choices and saved preset models. For edits, preserve the source model inherited by the tool unless the user requests a model change.
- Check `list_generation_models` for current availability and prices. Nano Banana 2.1 retains NB2's base 12 / 18 / 30 credits at 1K / 2K / 4K at release. Source resolution is separate from the requested pixel-art dimensions and does not guarantee an exact final canvas size.
- For transparent sprites, continue using `background="transparent"`; SpriteCook removes the background after generation. NB2.1 does not produce native alpha transparency.
- Keep the MCP tool's reference limits: `style_asset_ids` accepts at most 10 IDs, plus the supported reference or edit asset. The provider's 14-image total limit does not increase this tool's argument limit.
- Complete UI kits follow `spritecook-build-ui-kits` and its own model default.

## Tool

### `generate_game_art`

Generate game art assets from a text prompt. Supports both pixel art and detailed/HD styles. Returns a job immediately by default; follow the returned `poll.tool` and `poll.arguments` until the assets are ready. Pass `wait_seconds` only when an explicit bounded wait is useful.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string (required) | - | What to generate. Be specific about subject, pose, and view angle |
| `width` | int | 64 | Width in pixels (16-512) |
| `height` | int | 64 | Height in pixels (16-512) |
| `variations` | int | 1 | Number of variations (1-4) |
| `pixel` | bool | true | True for pixel art, false for detailed/HD art |
| `bg_mode` | string | "transparent" | "transparent", "white", or "include" |
| `theme` | string | null | Art theme context, e.g. "dark fantasy medieval" |
| `style` | string | null | Style direction, e.g. "16-bit SNES style" |
| `aspect_ratio` | string | "1:1" | "1:1", "16:9", or "9:16" |
| `smart_crop` | bool | true | Auto-crop to content bounds |
| `smart_crop_mode` | string | "tightest" | Use `"tightest"` by default. Use `"power_of_2"` only when explicitly requested |
| `model` | string | null | Optional generation model. Call `list_generation_models` for current options and costs. |
| `mode` | string | "assets" | "assets", "texture", or "ui". Use `"ui"` only for one isolated UI asset; use `spritecook-build-ui-kits` for screens or systems. |
| `resolution` | string | "1K" | "1K", "2K", or "4K" |
| `quality` | string | "medium" | GPT-Image-2 quality tier: "low", "medium", or "high". Higher quality costs more credits. |
| `colors` | string[] | null | Hex color palette, max 64 |
| `style_asset_ids` | string[] | null | Owned asset IDs to use as ambient style guide images, max 10 |
| `reference_asset_id` | string | null | Asset ID to use as one specific visual/context reference |
| `edit_asset_id` | string | null | Asset ID to edit/modify with the new prompt |
| `wait_seconds` | int | 0 | Optional bounded wait from 0-90 seconds before returning the polling contract |

Referenced assets must belong to the user's account. `style_asset_ids` can be combined with either `reference_asset_id` or `edit_asset_id`. Do not combine `reference_asset_id` and `edit_asset_id`.

If the user provides local image file paths for these references, use `spritecook-upload-assets` first and pass the returned asset IDs into the appropriate reference field.

## Reference Roles

- Use `style_asset_ids` for style guide images: ambient style, palette, proportions, rendering, and art-direction context. This is the normal choice when generating a new related asset that should match an existing collection, such as giving three existing buildings as style guides before asking for a new building type. SpriteCook already treats these images as style references; mention them in the prompt only when the user wants a specific trait called out.
- Use `reference_asset_id` when one specific asset is the source or context for the prompt, such as `make a building in a similar style to this one`, `give me just the door sprite`, or `use this character as the visual reference`.
- Use `edit_asset_id` when the user wants a direct modification of one existing asset, such as `make this roof red`, `remove the sign`, or `change the helmet color`.

### `list_generation_models`

List available still-image generation models, pixel-art support, reference-image limits, supported quality options, and SpriteCook credit costs per image. Call this when choosing a model or when the user asks what models/costs are currently available.

### `list_character_workflows`

List guided pixel-art character perspectives, default animation ids, source-view/prep requirements, frame counts, and credit estimates.

Perspectives and preset animations:

| Perspective | Defaults | Presets |
|-------------|----------|---------|
| `platformer` | `idle`, `walk`, `jump` | `idle`, `walk`, `jump`, `run`, `attack`, `hurt`, `death` |
| `isometric` | `idle`, `walk_down`, `walk_right` | `idle`, `idle_back`, `walk_down`, `walk_right`, `jump_back`, `jump_front`, `run_down`, `run_right`, `attack`, `hurt`, `death` |
| `topdown` | `idle`, `walk_up`, `walk_right`, `walk_down` | `idle`, `idle_back`, `idle_right`, `walk_up`, `walk_down`, `walk_right`, `attack`, `hurt`, `death` |

### `generate_character`

Generate a base pixel-art character with SpriteCook's recommended character settings: 64x64, transparent background, 1K square, tight smart crop, and the perspective-specific character prompt rewrite. Returns a job immediately by default; when complete, the first generated asset is the `character_id`.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string (required) | - | Character description |
| `perspective` | string (required) | - | `platformer`, `isometric`, or `topdown` |
| `model` | string | null | Optional generation model. Call `list_generation_models` for current options and costs. |
| `quality` | string | "medium" | GPT-Image-2 quality tier: "low", "medium", or "high" |
| `wait_seconds` | int | 0 | Optional bounded wait from 0-90 seconds before returning the polling contract |

### `generate_character_animations`

Generate preset and/or custom animations for a base character asset. Returns a character-animation run immediately by default; follow the returned polling contract until canonical `assets` entries are ready.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `character_id` | string (required) | - | Base character asset id returned by `generate_character` |
| `perspective` | string (required) | - | Same perspective used for the base character |
| `animation_ids` | string[] | perspective defaults | Preset ids from `list_character_workflows` |
| `custom_animations` | object[] | null | Custom animations with `{ id, label, prompt, source_view, output_frames }` |
| `bg_removal_provider` | string | "basic" | `basic` or `photoroom` |
| `wait_seconds` | int | 0 | Optional bounded wait from 0-90 seconds before returning the polling contract |

Custom animations use the custom prompt as the final animation prompt and skip preset prompt enhancement. `source_view` defaults to `front_idle`; if another source view needs prep, SpriteCook uses the matching workflow prep dependency for that perspective.

Example custom animation:

```json
{
  "label": "Spin Attack",
  "prompt": "Spin in place with a quick sword slash, looping cleanly.",
  "source_view": "right_walk",
  "output_frames": 8
}
```

### `check_character_animation_run`

Check a guided character animation run by id. Returns run status, item statuses, canonical generated `assets`, prep state, failures, and credits.

## Async Result Contract

- Follow the returned `poll.tool` with its exact `poll.arguments`; use `check_job_status` for jobs and `check_character_animation_run` for character-animation runs.
- Treat `operation_id` as the generic operation identifier while retaining `job_id` or `run_id` for the matching poll tool.
- On success, use each asset's `asset_id` and `sprite_url`. Use `spritesheet_url` only when an animation also provides a spritesheet.
- If a successful response contains `warning.code="asset_output_unavailable"`, execute the supplied `warning.recovery` tool call instead of searching arbitrary nested URL fields.

## Working Style

- Be specific about subject, pose, camera/view angle, and key materials.
- Call `list_generation_models` when current model names, pixel-art support, quality options, or credit costs matter.
- When the user asks to use a saved preset, use `list_presets` and `get_preset_settings` first, then map the returned prompt, style, model, size, color, and reference guidance into `generate_game_art`.
- Use `list_character_workflows`, `generate_character`, and `generate_character_animations` when the user wants a directly usable animated character set.
- Route menus, HUDs, inventories, dialogs, settings screens, overlays, and other complete UI compositions to `spritecook-build-ui-kits`.
- Default to pixel art unless the user asks for HD, detailed, smooth, realistic, or high-res output.
- When the user wants the same character or item in multiple outputs, generate one canonical still asset first and reuse that asset ID.
- Use `style_asset_ids` for follow-up generations that should keep the same visual style, especially when a preset returns `settings.reference.styleAssetIds`.
- Use `reference_asset_id` when the prompt depends on one specific visual/context reference asset.
- Use `edit_asset_id` when directly modifying one existing SpriteCook asset.
- Do not generate multiple independent still variations when the real goal is one consistent character plus later animations.
- Prefer `smart_crop_mode="tightest"` unless the user explicitly asks for `"power_of_2"`.

## Consistency Rules

- For a motion set like idle, walk, attack, or hurt: generate the base character once, then animate that exact `asset_id` separately for each motion.
- For asset variations that should stay recognizably the same design, prefer `edit_asset_id` for direct modification or `style_asset_ids` for style guidance over a brand-new unreferenced generation.
- Only skip a reference when the user explicitly wants different designs to explore.

## Pixel Art vs Detailed Art

**Pixel art** (`pixel: true`, default):
- Crisp hard edges, no anti-aliasing, visible pixel grid
- Automatic pixel-perfect post-processing for clean grid alignment
- Best for retro games, indie games, and 8-bit/16-bit projects

**Detailed/HD art** (`pixel: false`):
- Smooth gradients, fine detail, anti-aliased edges
- Higher fidelity output without pixel grid constraints
- Best for HD 2D games, concept art, and marketing assets

Choose based on the game's art direction. When the user does not specify, default to pixel art.