Guide · Agent skill
How to use the Hatch Pet agent skill: install and run it
Updated · written with AI from the project's own documentation and checked against our catalogue data
Hatch Pet is an agent skill that guides an AI agent through building an animated, pixel-style desktop pet from a character drawing, screenshots, or a text concept. It plans the animation rows, asks the image-generation skill for each row of poses, then uses bundled scripts to cut frames, check them, assemble an 8x9 spritesheet, make QA previews and package a pet.json file. This guide explains what the skill does, how to install it, how to trigger it, and what it needs before you start.
Hatch Petnexu-io/open-design · Apache-2.0 Download the skill Quick start
- 1Confirm $imagegen is installed. Check that the imagegen SKILL.md file exists under ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/. The workflow will not run without it.
- 2Download and unzip hatch-pet. Download the hatch-pet ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 3Make a request. Describe your pet and mention the hatch-pet skill, for example by asking to hatch a pet from your drawing.
- 4Approve image generation. Let the agent run the $imagegen jobs, and confirm any CLI fallback it asks about.
- 5Review the QA output. Check qa/contact-sheet.png and the preview media. Ask for repairs on any row that breaks the rules.
- 6Import the packaged pet. Find the pet under ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/ and import the spritesheet via Settings → General → Pets → Import Codex sprite.
What is an agent skill, and what does hatch-pet do?
An agent skill is a folder with a SKILL.md file and optional scripts and reference notes. When you ask a compatible agent for a matching task, the agent reads the instructions and follows them. Hatch Pet is one such skill, and its job is narrow: turn character art into an animated pet that a floating pet companion app can play.
The output is a 1536x1872 spritesheet arranged as 8 columns by 9 rows, with each cell 192x208 pixels. Each row is an animation state such as idle, running-right, waving or jumping. The skill also writes a pet.json manifest so the app can find the sheet.
- Plans the nine animation rows and their frame timings
- Generates row art through the installed $imagegen skill (it does not draw frames itself)
- Extracts and checks frames, then assembles the final atlas
- Creates QA contact sheets and preview media, and packages pet.json
Install the hatch-pet skill
Download the hatch-pet ZIP from this page and unzip it. For a personal setup, place the hatch-pet folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder instead.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/hatch-pet/
- Project install: .claude/skills/hatch-pet/ inside your project
Check the required $imagegen skill first
Hatch Pet depends on the $imagegen system skill. The skill expects it at ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md. If that file is missing, the workflow stops, because generating row strips locally is explicitly not allowed.
Image generation access through $imagegen is also required. Its fallback path may need your confirmation before it continues.
- Confirm the imagegen SKILL.md file exists at the path above
- Be ready to approve a CLI fallback if $imagegen asks
Trigger the skill with a natural request
You do not need special syntax. Describe the pet and mention that you want the skill used. The skill's trigger phrases include "hatch a pet", "hatch pet", "codex pet", "spritesheet pet" and "animated pet". Optional details such as a name or description are inferred from your concept or reference filenames if you leave them out.
If you give no reference images, the skill generates a base pet from your text first and uses it as the reference for every row.
- "Hatch a pet from this drawing: friendly red fox, sitting upright. Use the hatch-pet skill."
- "Make me an animated pixel-art shiba with a small pomegranate prop, using hatch-pet end-to-end."
- "Repair the running-right row of my codex pet in ./mypet and re-package it."
What the run produces and where it goes
The main output is final/spritesheet.png, with final/spritesheet.webp, pet.json and qa/contact-sheet.png as secondary outputs. After packaging, the skill places the files in ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/. The folder must contain pet.json and spritesheet.webp, and the app loads the pet from the folder name.
To use it in the companion app, the source says to open Settings → General → Pets → Import Codex sprite. The import flow detects the 8x9, 192x208 atlas and lets you choose which row to play.
- pet.json fields: id, displayName, description, spritesheetPath
- Animation rows include idle, running-right, running-left, waving, jumping, failed, waiting, running and review
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
├── pet.json
└── spritesheet.webpSafety notes: scripts and network use
This skill runs bundled Python scripts and uses the network, because image generation happens through $imagegen. The source does not list the Python dependencies, so check what the scripts need before running them in an environment you care about.
Each normal run can involve up to 10 image-generation jobs: one base pet and nine row strips. Plan for that cost before you start. The skill also prohibits drawing pet art with local code as a substitute for generation.
- Expect up to 10 generation jobs per normal run
- Review any fallback that $imagegen asks you to confirm
- Install the Python dependencies yourself; they are not listed in the provided files
Tips for better pet results
The skill favours a simple, chunky pixel-mascot look. Detailed or realistic references are simplified into that style on purpose, so a polished illustration will not come out polished. Choose a clear silhouette and a limited palette in your reference.
Avoid effects such as motion lines, shadows, glow or floating sparkles. The skill's rules reject them because they break transparent background cleanup. If a row fails QA, ask the agent to repair that row rather than starting over.
- Use a simple, readable silhouette and few colours
- Prefer pose and expression changes over decorative effects
- Ask for a repair of a single row if one state looks wrong
What people use it for
- Creating a custom pixel-style desktop companion from a sketch of your own character
- Building a repeatable Codex pet asset for a developer project
- Turning an existing character drawing into a small sprite animation with nine states
- Repairing one animation row, such as running-right, without rebuilding the whole pet
Frequently asked questions
Is the hatch-pet skill free?
The source identifies the licence as Apache-2.0. It does not list prices, so check the page for any cost details. Note that a normal run can involve up to 10 image-generation jobs, which the source describes as costly.
What do I need to install before using hatch-pet?
You need the $imagegen system skill installed at ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md, image generation access through that skill, Python for the bundled scripts, and an agent environment such as Codex or a compatible tool.
Where do I put the hatch-pet folder?
Unzip it into ~/.claude/skills/ for a personal install, or into .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does hatch-pet work without a reference image?
Yes. If you omit reference images, the skill generates the base pet from text first, then uses that base as the canonical reference for every animation row.
Can I use hatch-pet to make a single static image?
The source says not to, because a normal run involves up to 10 image-generation jobs and is costly. It is designed for animated spritesheets.
How does hatch-pet compare with other pet or sprite tools?
The source does not compare hatch-pet with other tools, so this guide cannot make a comparison. It is built for the Codex pet atlas format and the companion app's import flow, and it is not meant for full-resolution or realistic animation.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Hatch Pet suits creators who want a custom pixel-style desktop pet, developers who need a repeatable Codex atlas workflow, and artists turning an existing drawing into a small animation. Skip it if you need realistic or full-resolution animation, a single static image, or if you cannot install the $imagegen skill.
Download the skill