Open Design Hatch Pet Skill Guide

Skill Overview

Hatch Pet is a complete Codex digital pet hatching skill that can create a Codex-compatible animated sprite pet from a concept description, reference images, or both. The output is a 1536×1872 (192×208 × 8 columns × 9 rows) atlas spritesheet, containing 9 animation states (idle, running-right, running-left, waving, jumping, failed, review, etc.), with a QA contact sheet, preview video, and pet.json configuration.

The default style matches Codex built-in pets: a small pixel-art-adjacent mascot, chibi proportions, a thick 1-2px dark outline, a limited color palette, flat cel shading, simple expressions, and small hands and feet.

Trigger Keywords

hatch a pet, hatch pet, codex pet
spritesheet pet, animated pet
hatch pet, digital pet

When to use

Want to create a custom animated pet as a Codex companion
Need to generate corresponding animated sprites from a character design draft
Want to repair the animation rows of an existing pet (repair workflow)
Need to package pet.json + spritesheet.webp for Codex import

Usage

Visible progress plan

The entire hatching process is tracked with a 4-step progress checklist:

Getting <Pet> ready, confirm the pet name, description, reference image, and working directory
Imagining <Pet>'s main look, generate the main reference image (required for new pets, even if the user did not provide an image)
Picturing <Pet>'s poses, create pose rows, first generate idle and running-right to confirm consistency
Hatching <Pet>, convert the approved poses into final files, review the contact sheet, preview, and validate the results

Standard workflow

Prepare the run directory and manifest, use prepare_pet_run.py to create the working directory and generate prompt files and layout guides for 9 rows
Check ready jobs, use pet_job_status.py to view the next available $imagegen task
Generate the base pet, use $imagegen to generate the base job, record the result, then write it to decoded/base.png and references/canonical-base.png
Generate animations row by row, use subagents to generate 9 animation rows in parallel (except running-left may be derived by mirroring running-right)
Record results, use record_imagegen_result.py to copy $imagegen output to the correct decoded path
Finalize, run finalize_pet_run.py to output the complete structure:

run/
├── pet_request.json
├── imagegen-jobs.json
├── prompts/
├── decoded/
├── frames/frames-manifest.json
├── final/spritesheet.png + spritesheet.webp + validation.json
├── qa/contact-sheet.png + review.json + run-summary.json
└── qa/videos/*.mp4

Package, write to ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/pet.json + spritesheet.webp

Parallel generation with subagents

The parent is responsible for manifest and package writes; row-strip visual generation is performed in parallel using subagents:

The parent first spawns subagents for idle and running-right (identity synchronization check)
Check whether running-right is suitable for mirroring → running-left (symmetric, no handheld props, no direction dependence)
The remaining rows each spawn a subagent
Each subagent receives: row id, prompt file, all input image paths
The subagent returns only the selected source path + a one-sentence QA note

Transparency and effect rules

All effects must simultaneously satisfy:

Connected to, touching, or overlapping the pet silhouette (do not float)
Within the same frame slot, does not produce an independent sprite component
Opaque, hard-edged, pixel-style
Does not use colors close to the chroma-key

Prohibited effects: wave marks, speed lines, afterimages, detached stars, drop shadows, glow, halo, text/labels/grid lines/checkerboard, white/black backgrounds.

Repair workflow

If finalization stops because of a row QA failure:

python scripts/queue_pet_repairs.py --run-dir /path/to/run

Only regenerate the failed row, not the entire atlas.

Output

Primary: final/spritesheet.png (1536×1872)
Secondary: final/spritesheet.webp, pet.json, qa/contact-sheet.png
Packaged to: ~/.codex/pets/<pet-name>/

Acceptance Criteria

The final atlas is PNG or WebP, 1536×1872, supports transparency
Used cells are non-empty, unused cells are fully transparent
qa/review.json has no errors
Contact sheet and preview video have been generated
Identity is consistent per row (species/face/markings/color palette/props/silhouette unchanged)

Hard Rules

$imagegen is the primary generation layer; do not use local Python/Pillow/SVG/canvas as a substitute
Every row job must attach grounding images
Generate running-right first; derive running-left via mirror only when mirroring is safe
Do not manually modify imagegen-jobs.json to claim a visual job is complete
Visual identity drift is a blocker, even if validation.json has no errors

Example Use Cases

Custom AI assistant pet: A developer wants to create a unique animated pet for Codex as a daily companion, hatching it from a concept description. The 8×9 atlas includes 9 animation states such as idle, running, and waving. After generation, it is packaged into the ~/.codex/pets/ directory for direct use. Repairing an existing pet animation: An existing pet's jumping animation shows identity drift (inconsistent colors). Use the repair workflow to regenerate only the failed row instead of regenerating the entire atlas, saving generation time and quota.

Read these first