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.