35 added, 152 removed. Audit A to A.
---
name: animation-creator
- description: Create character animation runs from one preserved canonical base character. Codex plans the requested motion beat by beat, generates matte-background action sheets with $image-creator, removes action-sheet backgrounds with rembg, extracts validated frames, and produces project-local WebP animations.
+ description: Create character animations from a source image or character description, preserving identity across actions and exporting animated WebP assets.
---
# Animation Creator
- Create character animation assets from one canonical base character. Plan the requested motion one adjacent pose beat at a time, audit the beats, then generate a base character if needed and generate action sheets with `$image-creator`. Preserve the canonical base as the identity reference. Generated action sheets use a flat removable matte background because rembg removes that more reliably than fake transparency before frame extraction.
-
- This skill saves runs and final assets into the current session project by default.
-
- ## Core Model
-
- Every run has one canonical base character and one or more action jobs.
-
- - Use `$image-creator` for base and action image generation. Do not call image APIs directly.
- - Ask for the animation action when it is missing.
- - If the user provides a source character image, preserve it as `references/canonical-base.png` without rembg background removal.
- - If no source image exists, generate the base character first, then record it through `record_animation_result.py` without rembg background removal.
- - Reuse the existing canonical base for later actions unless the user explicitly asks for a new base.
- - Before preparing a run, build the per-frame action plan sequentially. Do not choose a frame count first.
- - Frame 1 may describe the starting pose. Every later frame should primarily describe the visible change from the previous frame, while scale, facing identity, body center path, balance, contact points, and weight transfer remain continuous.
- - Audit the completed frame action list for missing anticipation, contact, passing pose, follow-through, settle, or loop bridge. Delete duplicate silhouettes and tiny micro-steps. The final frame count is the audited beat count.
- - Avoid transform-like wording such as `flipped`, `mirrored`, `reversed`, `opposite direction`, or `rotate 180 degrees` unless the requested action truly needs that major transform.
-
- ## Hard Rules
-
- - The prompt text sent to `$image-creator` must be the exact stdout from `build_generation_prompt.py` for that job.
- - Do not create a separate `prompts/image-creator/` copy, and do not manually rewrite, summarize, shorten, or reconstruct the prompt.
- - Save run folders and final outputs in the current session project by default, normally under `animation-runs/<character-or-run-id>/`.
- - If the user gives a destination, resolve relative destinations from the session project root.
- - Do not draw, tile, warp, synthesize, or invent visual character frames with local scripts as a substitute for `$image-creator`.
- - Do not use old key-color cleanup or legacy background modes. The only supported generated-background contract is `rembg-matte`.
- - Raw generated action images must use a single flat solid vivid sky-blue removable matte background `#00B7FF`.
- - The matte color `#00B7FF` is reserved for background only; do not use it on character pixels, props, markings, motion effects, outlines, highlights, or shadows.
- - Final recorded action sheets and extracted frames must be true alpha PNGs created by rembg. Cut the raw action sheet into planned frame slots using the actual generated image size, strip the preserved outer black cell borders from each slot crop, run rembg on each stripped slot image, remove matte-color residue from the rembg slot output, then reassemble the alpha-normalized sheet. If rembg cannot run, stop and report the failure.
- - Run skill scripts with `uv run --project skills/animation-creator ...` so uv prepares the project-local `rembg[gpu,cli]` environment. Use GPU-backed rembg automatically when ONNX Runtime exposes `CUDAExecutionProvider` or `ROCMExecutionProvider`; if the GPU provider is unavailable or fails during execution, retry with CPU fallback and record the selected backend plus any fallback reason in manifest/job metadata.
- - Do not ask `$image-creator` for scene backgrounds, floors, horizons, rooms, skies, landscapes, gradients, textured backgrounds, fake checkerboard transparency, cast shadows, contact shadows, glows, dust, or landing marks.
- - Treat missing outer black cell borders in the raw action sheet, visible inner safe boxes, centerlines, guide marks, labels, captions, frame numbers, ghost characters, clipped body parts, repeated stills, wrong slot order, broken identity, or disconnected motion as failures. Final recorded sheets and extracted frames must not retain borders or guide lines.
- - Every action generation must attach the canonical base image. After the canonical base is recorded, also attach that action's registration guide as an edit template.
- - The generated raw action sheet should preserve the registration guide's 4:3 layout, outer boundaries, and outer black cell borders; replace guide characters with animated poses in used slots; leave unused slots empty; and remove only inner safe rectangles, centerlines, labels, ghost characters, and guide marks.
- - Use complete full-body poses by default. If the user wants a cropped bust, hand, icon, or partial-body animation, record that as an explicit output contract.
- - Do not accept deterministic validation alone as final proof. Review the contact sheet or final animation for identity drift and visible clipping.
-
- ## Workflow
-
- 1. Establish the run:
- - character source image or base character prompt
- - required action name and action description
- - playback timing, loop mode, output format, and destination if requested
- - per-frame action plan written specifically for this action
- - project root, defaulting to the current working directory
-
- 2. Plan frame actions sequentially:
- - Add one concrete adjacent beat at a time.
- - Prefer concrete spatial deltas over standalone pose labels.
- - Continue until the action has needed anticipation, contact or launch, key pose, passing/in-between poses, follow-through or overshoot, settle, and loop bridge or clear end pose.
- - Audit for too few frames, too many frames, repeated stills, missing transitions, and vague wording.
- - Only after the audit is clean may the list become `--frame-actions`.
-
- 3. Prepare a run folder and manifest:
-
- ```bash
- SKILL_DIR="skills/animation-creator"
- uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/prepare_animation_run.py" \
- --character-name "<Name>" \
- --character-prompt "<base character description>" \
- --action-id "<action-id>" \
- --action "<action description>" \
- --frame-actions "<frame 1 action>; <frame 2 action>; <frame N action>" \
- --project-root /absolute/path/to/session/project \
- --output-dir /absolute/path/to/run
- ```
-
- If a source image exists, pass it with `--source-character /absolute/path/to/image.png`. Source images are preserved as the canonical base.
-
- 4. If no source character was provided, generate the base character with `$image-creator`:
-
- ```bash
- uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/build_generation_prompt.py" \
- --run-dir /absolute/path/to/run \
- --job-id base-character
- ```
-
- Send stdout exactly as the final `$image-creator` prompt. Save the generated raw image, then record it:
+ Use one canonical character per run and `$image-creator` for every generated base or action sheet. Do not synthesize character frames with local drawing, tiling, or warping scripts.
- ```bash
- uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/record_animation_result.py" \
- --run-dir /absolute/path/to/run \
- --job-id base-character \
- --source /absolute/path/to/generated/base.png
- ```
+ Set `SKILL_DIR` to this skill's absolute directory. Run helpers with `uv run --project "$SKILL_DIR"` from the session project. Default runs to `animation-runs/<run-id>/`; resolve requested relative destinations from the project root.
- Recording stores the raw image under `generated/raw/base-character.png`, writes the preserved canonical image to `references/canonical-base.png`, and refreshes action prompts and registration guides.
+ ## Plan the Action
- 5. For each action job, call `$image-creator` with:
- - the action prompt built by `build_generation_prompt.py`
- - `references/canonical-base.png` as the character identity input
- - `references/registration-guides/<action-id>.png` as an edit template whose canvas size should be preserved
- - an attempt destination inside the run directory, normally `generated/attempts/<action-id>-NN.png`
+ Establish the character source and requested action; ask for the action if missing. Use requested timing and loop settings, defaulting to a looping WebP with full-body poses. Record an explicit partial-body request as the output contract.
- Review the raw generated action sheet before recording it:
- - canvas aspect and 4x3 layout match the registration guide
- - requested slots contain exactly one full-body pose each, left-to-right then top-to-bottom
- - outer black cell borders are present in the raw sheet
- - the sheet background is one flat vivid sky-blue matte `#00B7FF`
- - no visible inner safe boxes, centerlines, labels, captions, frame numbers, ghost characters, guide marks, or scene background are present
- - character identity, scale, facing identity, and camera distance remain stable
- - adjacent frames read as one continuous motion
+ Build adjacent motion beats before choosing a frame count. Each beat after the starting pose should describe the visible change from its predecessor, preserving character scale, facing, body-center path, balance, contact, and weight transfer.
- Record only the selected raw image that passed review. Recording cuts the sheet into planned slots, runs rembg on each slot, removes matte-color residue, and reassembles the transparent action sheet:
+ Audit for needed anticipation, contact or launch, passing poses, follow-through, settling, and loop bridge or clear end pose. Remove duplicate silhouettes and tiny redundant steps. The audited beat count becomes the frame count, up to 12. Avoid flip/mirror/rotation language unless the action actually needs that transformation.
- ```bash
- uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/record_animation_result.py" \
- --run-dir /absolute/path/to/run \
- --job-id <action-id> \
- --source /absolute/path/to/generated/action-grid.png
- ```
+ ## Prepare or Extend
- 6. Finalize post-processing:
+ For a new run, read [references/run-setup.md](references/run-setup.md). Preserve the source or generated base as `references/canonical-base.png` without background removal.
- ```bash
- uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/finalize_animation_run.py" --run-dir /absolute/path/to/run --action-id <action-id>
- ```
+ For a later action, reuse the run and canonical base unless the user requests a new character:
- This checks recorded generated-job files, extracts frames from the rembg-normalized alpha sheet, writes validation JSON, composes the PNG frame sheet, creates a contact sheet, writes the final animated WebP, and records `qa/run-summary.json`.
+ ```bash
+ uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/prepare_animation_run.py" \
+ --run-dir <run-dir> --add-action --action-id <action-id> \
+ --action "<description>" --frame-actions "<beat 1>; <beat 2>; <beat N>"
+ ```
- 7. Inspect validation JSON, contact sheet, and final WebP animation. Repair only the failed action when possible.
+ Read [references/animation-output-contract.md](references/animation-output-contract.md) before generating an action sheet when that contract is not already in context. The current pipeline requires `rembg-matte` raw sheets and rembg-normalized alpha outputs.
- ## Adding Actions To An Existing Run
+ ## Generate and Record
- For additional actions, reuse the run directory:
+ Build the prompt for the base job or selected action:
```bash
- uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/prepare_animation_run.py" \
- --run-dir /absolute/path/to/run \
- --add-action \
- --action-id "<new-action-id>" \
- --action "<new action description>" \
- --frame-actions "<frame 1 action>; <frame 2 action>; <frame N action>"
+ uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/build_generation_prompt.py" \
+ --run-dir <run-dir> --job-id <job-id>
```
- Then generate only that new action through `$image-creator`, record it through `record_animation_result.py`, and run `finalize_animation_run.py` for that action.
+ Give stdout to `$image-creator` as the authoritative final prompt, unchanged. Do not rewrite it or maintain a separate `prompts/image-creator/` copy.
- ## Prompt References
+ For each action, supply both `references/canonical-base.png` as identity input and `references/registration-guides/<action-id>.png` as the edit template. Save attempts under the run's `generated/attempts/` with non-overwriting names.
- Read only the reference needed for the current step:
+ Inspect the returned raw action sheet against the output contract: fixed grid and slot order, complete poses, reserved matte, retained outer cell borders, removed inner guides, and continuous character identity and motion. Record only a selected image that passes this review:
- - `references/animation-output-contract.md` for frame size, frame count, matte background, rembg removal, format, and manifest expectations.
- - `references/qa-rubric.md` before accepting an action as complete.
+ ```bash
+ uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/record_animation_result.py" \
+ --run-dir <run-dir> --job-id <job-id> --source <saved-source-image>
+ ```
- ## Defaults
+ Recording a base preserves it and refreshes action prompts/guides. Recording an action performs per-slot rembg processing and reassembles the alpha sheet. If processing fails, report the error; do not substitute a different background-removal pipeline.
- - nominal registration-guide cell size: `362x362`
- - generated registration guides use a fixed `4x3` layout at `1448x1086`
- - safe margin: `30px` horizontal and `24px` vertical inside each nominal cell
- - frame count: derived from the completed per-frame action plan
- - default layout: derived from the finalized frame count
- - maximum frame count: `12`
- - output format: `webp`
- - final WebP path: `final/<action-id>.webp`
- - background mode: `rembg-matte`
- - removal matte: `#00B7FF` vivid sky-blue background-only matte
- - background removal engine: required `rembg`
- - background removal model: `birefnet-general-lite`
- - background removal uv extra: `rembg[gpu,cli]`
- - background removal backend: `cuda` or `rocm` when available through ONNX Runtime, otherwise `cpu`
- - background removal fallback: retry with `CPUExecutionProvider` when a GPU provider is detected but rembg execution fails
- - loop mode: loop
+ ## Finalize and Review
- ## Response
+ ```bash
+ uv run --project "$SKILL_DIR" "$SKILL_DIR/scripts/finalize_animation_run.py" \
+ --run-dir <run-dir> --action-id <action-id>
+ ```
- When finished, report:
+ Read [references/qa-rubric.md](references/qa-rubric.md) before acceptance. Review validation results, the contact sheet, and animation where a viewer is available; deterministic checks alone cannot establish identity or motion quality. Repair the failed action or processing step without recreating valid work.
- - run directory
- - project-local output directory
- - canonical base image path
- - generated action IDs
- - final WebP animation file paths
- - contact sheet and validation paths
- - whether `$image-creator` was used for the base, actions, or both
- - any repairs, skipped outputs, or visual review concerns
+ Report the run and canonical-base paths, generated action IDs, final WebP links, contact-sheet and validation links, use of `$image-creator` for base/actions, and repairs, omissions, or visual-review limitations.