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:

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:

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.

{
  "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)

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

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:

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

Safe to re-run — completed strips are skipped.

Step 9 — Extract and build atlas (free)

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 — atlas row spec with frame counts and durations
• references/cost-reference.md — per-image pricing