# Hatch Pet

> Generate animated pixel art pet sprites from a text description or reference image. Outputs a Codex-compatible 1536x1872 sprite atlas with up to 9 animation states. Use this skill whenever the user wants to create a pet, sprite, animated character, pixel art avatar, or game character — even if they don't say "hatch" or "sprite" explicitly. Also use when the user provides a character image and wants it turned into an animated sprite, or asks to generate/regenerate animation states for an existing pet.

- Skill: `win-hao/hatch-pet` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add win-hao/hatch-pet`
- Raw SKILL.md: https://api.skillmd.com/api/skills/win-hao/hatch-pet/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: win-hao (https://skillmd.com/u/win-hao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/win-hao/hatch-pet

---


# Hatch Pet

Generate animated pet sprites through a guided conversation. Follow these steps in order.

## Step 0 — Show what's possible

Start by showing the user an example so they know what to expect.
Read and display one of the example preview GIFs: `${CLAUDE_SKILL_DIR}/examples/homelander/previews/idle.gif`

Tell the user something like:
> Here's an example of what this skill produces — an animated pixel art character with multiple states (idle, running, waving, etc.). Let's create yours!

## Step 1 — What character?

Ask the user to describe their character. If they provide a reference image, save it as
`<pet-name>/reference.<ext>` (this helps the AI match the look).

Then ask for a **name** — this becomes the directory name (kebab-case).

## Step 2 — Pick a style

Show these options and ask the user to pick one:

| Style | Look |
|-------|------|
| **pixel** | Chunky pixel art with dark outlines and flat shading (recommended) |
| **plush** | Soft plush toy with stitched details |
| **clay** | Handmade clay figure, rounded and tactile |
| **sticker** | Bold shapes, crisp outlines, flat colors |
| **flat-vector** | Simple geometric forms, clean and minimal |
| **3d-toy** | Smooth 3D toy with simple materials |
| **painterly** | Brush texture, painterly feel |

Default to `pixel` if the user doesn't have a preference.

## Step 3 — Pick quality and states

Ask: "Medium quality is recommended (~$0.25 for the full set). Low is cheaper (~$0.06) but less detailed. Which do you prefer?"

For animation states, suggest the default set and ask if they want to add or remove any:
- `idle` — Breathing/blinking resting loop
- `running-right` — Moving rightward (running-left auto-mirrored)
- `waving` — Greeting gesture
- `failed` — Sad/slumped reaction

Additional states available: `jumping`, `waiting`, `running` (working/processing), `review`.

## Step 4 — Check dependencies and API

First, check that Python dependencies are installed:
```bash
python3 -c "import PIL, numpy, httpx" 2>&1 || pip3 install Pillow numpy httpx
```

Then check if `.env` exists in the working directory. If not, tell the user:

> This skill needs an OpenAI-compatible API with **GPT-Image-2** support. That's the only model
> that can draw multiple animation frames in a single image.
>
> I'll need your **API Base URL** and **API Key**. (Your key will be stored locally in `.env`
> and never committed or displayed.)

Write `.env`:
```
HATCH_PET_PROVIDER=openai
HATCH_PET_API_KEY=<key>
HATCH_PET_BASE_URL=<url>
HATCH_PET_MODEL=gpt-image-2
```

**Never log, display, or commit the API key.** Mask it when confirming (`sk-...xxxx`).

## Step 5 — Create pet config

Create `<pet-name>/pet.json` based on the user's answers. Enrich the user's character
description with specific visual details that help image generation — proportions
(e.g., "2.5 head-to-body ratio"), colors, materials, key features. Keep it one paragraph.

```json
{
  "name": "<kebab-case>",
  "displayName": "<Display Name>",
  "description": "<enriched visual description>",
  "style": "pixel",
  "quality": "medium",
  "chroma_key": "auto",
  "states": ["idle", "running-right", "waving", "failed"],
  "derive_running_left": true
}
```

## Step 6 — Prepare (free)

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/prepare.py ./<pet-name>
```

Show the summary and estimated cost. Ask the user to confirm before spending money:
> This will cost approximately $X.XX. Ready to start?

## Step 7 — Preview

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/generate.py ./<pet-name> --preview
```

Show the generated base image to the user and ask:
> Does this look like what you want? I can regenerate if you'd like changes.

If not satisfied, delete the preview, adjust the prompt, and re-run:
1. `rm <pet-name>/.hatch/decoded/base.png`
2. Edit `<pet-name>/.hatch/prompts/base.md` based on feedback
3. Re-run `--preview`

## Step 8 — Generate all strips

After the user approves the preview:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/generate.py ./<pet-name>
```

Safe to re-run — completed strips are skipped.

## Step 9 — Extract and build atlas (free)

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/extract.py ./<pet-name>
```

Show the preview GIFs to the user so they can see each animation in action.

## Step 10 — Quality check

If any animation state looks off (frame drift, inconsistency, characters too close):
1. `rm <pet-name>/.hatch/decoded/<state>.png`
2. Re-run generate.py then extract.py

The API is non-deterministic — retries often produce better results.

After the user is happy, let them know their files are in `<pet-name>/`:
> Your sprite atlas is ready at `<pet-name>/spritesheet.png` (and `.webp`).
> Preview GIFs for each animation are in `<pet-name>/previews/`.
> Want to create another character?

## Rules

- **Never commit `.env`**
- **Cost awareness** — always confirm cost before API calls
- **No example strips as reference** — only the canonical base and layout guide should be passed to the edits API
- Each pet gets its own directory — no cleanup needed between characters

## User's directory structure

```
working-directory/
├── .env                          # API credentials (created once)
├── iron-man/                     # One directory per pet
│   ├── pet.json                  # Pet config
│   ├── reference.webp            # Optional reference image
│   ├── spritesheet.png           # Final atlas (after extract)
│   ├── spritesheet.webp
│   ├── previews/                 # Animation preview GIFs
│   └── .hatch/                   # Working files (can gitignore)
└── homelander/
    └── ...
```

## Additional resources

- [references/animation-rows.md](references/animation-rows.md) — atlas row spec with frame counts and durations
- [references/cost-reference.md](references/cost-reference.md) — per-image pricing