Character Animation Skill

English | 简体中文

A local Agent skill for turning a user-supplied or ImageGen-created character reference image into a short action video, PNG animation frames, and a sprite sheet.

The included provider is configured through a generic image-to-video API adapter. API keys are read from environment variables only.

Quick start

Requirements:

• Python 3.10+
• FFmpeg available on PATH
• Pillow
• PyYAML
• requests

Install Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Copy configuration:

cp config.example.yaml config.yaml
cp .env.example .env

Set your video API key in the shell environment. Do not paste secrets into source code or commit .env.

export VIDEO_API_KEY="your-api-key"

You can start from either:

• an existing character image supplied by the user; or
• a new character reference generated with ImageGen inside Codex.

For generated references, create a single full-body 2D character on a simple or transparent background, then use that image as the --image input.

The provider must implement:

generate(image_path, prompt, duration, output_path) -> local_video_path

Once configured:

python scripts/generate_video.py --image character.png --action "walk" --duration 4 --loop --output output/source.mp4
python scripts/extract_frames.py --video output/source.mp4 --output-dir output/raw_frames --fps 8
python scripts/align_frames.py --input-dir output/raw_frames --output-dir output/frames
python scripts/build_spritesheet.py --input-dir output/frames --output output/spritesheet.png

Read SKILL.md for the Agent workflow and first-run setup behavior.

Example

This repository includes one authorized example:

• examples/chara.png: source character sheet.
• examples/reference_frame.png: cropped first frame used for image-to-video.
• examples/source_4s.mp4: generated 4-second source video.
• examples/spritesheet_8frames.png: compact 8-frame transparent sprite sheet.
• examples/walk_cycle_8frames_preview.gif: animated preview.

Generated working files should stay under output/, which is ignored by Git.