# Create Clean Codex Pet > Create or repair installable Codex Desktop pets with character-specific motion, the full 9-state atlas contract, visually clean transparent edges, and large transparent showcase GIFs. Use when Codex needs to turn character art, an avatar, mascot, pet photo, or text concept into pet.json plus spritesheet.webp; when a pet's poses feel generic, lifeless, repetitive, or semantically unclear; when a generated pet has chroma-key halos, magenta or green fringe, dirty semi-transparent pixels, or rough cutout edges; when a pet must be validated on dark and light backgrounds; or when the user asks for a showcase GIF, display GIF, shareable GIF, large GIF, or animated pet preview. - Skill: `xue-xiaobao/create-clean-codex-pet` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add xue-xiaobao/create-clean-codex-pet` - Raw SKILL.md: https://api.skillmd.com/api/skills/xue-xiaobao/create-clean-codex-pet/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: xue-xiaobao (https://skillmd.com/u/xue-xiaobao) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xue-xiaobao/create-clean-codex-pet --- # Create Clean Codex Pet Compose the installed `$hatch-pet` workflow for production, add a lightweight character-motion pass before row generation, then enforce a mandatory edge-quality gate. Treat motion design, structural validation, and visual edge validation as separate requirements. ## Workflow 1. Read and follow the installed `$hatch-pet` skill. Use its current atlas geometry, state semantics, generation, repair, validation, packaging, and cleanup rules as authoritative. 2. For a new pet or motion repair, write a compact `references/action-brief.md` before preparing row prompts. Define one personality contradiction, one motion signature, one idle micro-action, and a distinct intention for every state. Read [references/action-design.md](references/action-design.md) only for this motion-design work; skip it for edge-only repair, packaging, or unchanged reinstallation. 3. Keep one canonical full-body identity image. Generate each required state from that reference and the action brief. Add only the matching state cue to each row prompt; do not paste the full brief into every prompt. Repair only the smallest failing row. 4. Use the chroma key stored in `pet_request.json`. Choose a key that does not conflict with the character; magenta is usually safer for blue characters. 5. Finish the normal hatch-pet pipeline before edge cleanup. Require the expected atlas dimensions, state rows, frame counts, alpha channel, and zero structural errors. 6. Inspect contact sheets and motion previews for personality, readable intent, and state separation before accepting visual generation. 7. Run the edge-quality gate below on the finalized atlas. 8. Promote and install only the cleaned candidate that passes motion, structure, and dark/light edge inspection. Keep the prior atlas as a backup. 9. When the user mentions a showcase or display GIF, create and directly show the large transparent GIF defined below from the accepted cleaned atlas. ## Motion-quality gate Keep movement readable inside a `192x208` cell. Prefer silhouette, gaze, weight shift, timing, asymmetry, anticipation, and follow-through over detached effects or new props. Require: - one consistent motion language across all rows: rhythm, weight, amplitude, reaction speed, and use of space - a recognizable motion signature that appears with restrained variation rather than in every frame - visible micro-variation in `idle` - clearly different intentions for `waiting`, task-active `running`, and `review` - readable directional gait in `running-right` and `running-left` - action-result or recovery character in expressive rows such as `jumping` and `failed`, when frame count permits - no row that could be transferred unchanged to an unrelated character without losing meaning Do not force a five-beat story into every loop. Use the fuller motivation-preparation-action-result-aftereffect arc only when it improves the state at pet scale. If motion fails but identity and edges pass, repair the smallest affected row; do not treat technical validity as motion acceptance. ## Showcase GIF default When the user asks to show, display, preview, or share the pet as a GIF, default to one large transparent montage GIF instead of only separate state GIFs: - `1280x800`, looping for 6 seconds - five simultaneous actions: `idle`, `waving`, `running-right`, `jumping`, and `failed` - three sprites on the top row and two centered on the bottom row - fully transparent background using GIF binary alpha - no text, labels, borders, scenery, shadows, or decorative background - preserve each state's native timing while sampling them on one shared timeline Generate it only from the promoted clean atlas: ```bash python3 "$SKILL_DIR/scripts/render_pet_showcase_gif.py" \ --atlas "$RUN_DIR/final/spritesheet.webp" \ --output "$RUN_DIR/showcase/pet-showcase-transparent.gif" \ --qa-output "$RUN_DIR/showcase/pet-showcase-transparent-qa.png" \ --report-output "$RUN_DIR/showcase/pet-showcase-transparent.json" \ --force ``` Require the report to have `ok: true`. Inspect the QA image on dark and light backgrounds, then embed the absolute GIF path in the final response so the animation is visible in conversation; do not provide only a filesystem link. A user's explicit request for separate GIFs, a solid background, labels, another layout, or another size overrides this default. Read [references/showcase-gif.md](references/showcase-gif.md) only when tuning, diagnosing, or changing the showcase GIF contract. ## Edge-quality gate Never accept a transparent atlas from a checkerboard preview or alpha statistics alone. Composite a representative frame over a dark background and a light background at 4x nearest-neighbor scale. Look for key-colored halos, pale outlines, dark contamination, broken whiskers, missing outline pixels, and silhouette erosion. Run the bundled cleaner non-destructively: ```bash SKILL_DIR=/absolute/path/to/create-clean-codex-pet RUN_DIR=/absolute/path/to/pet-run KEY=$(jq -r '.chroma_key.hex' "$RUN_DIR/pet_request.json") python3 "$SKILL_DIR/scripts/clean_pet_edges.py" \ --input "$RUN_DIR/final/spritesheet.webp" \ --output "$RUN_DIR/final/spritesheet-clean.webp" \ --key-color "$KEY" \ --qa-output "$RUN_DIR/qa/edge-before-after.png" \ --report-output "$RUN_DIR/qa/edge-clean-report.json" ``` The cleaner must: - preserve the `1536x1872` Codex atlas and every animation cell - remove chroma contamination from semi-transparent edge pixels - avoid alpha contraction by default so thin outlines and whiskers survive - normalize fully transparent pixels to RGBA zero - encode WebP losslessly with exact transparent RGB handling - produce a before/after dark/light QA image and JSON report Read [references/edge-quality.md](references/edge-quality.md) when diagnosing a failed edge gate or tuning thresholds. ## Acceptance Require all of the following: - the hatch-pet atlas validator reports no errors - the cleaner report has `ok: true` - width is `1536`, height is `1872`, and mode is RGBA - fully transparent pixels with non-zero RGB residue equal `0` - the before/after QA image shows no key-colored fringe on dark or light backgrounds - outlines, whiskers, paws, tail, and other thin features are not eroded - animation identity, frame count, scale, baseline, direction, and state semantics remain unchanged - the motion-quality gate passes and the nine states share one character-specific movement language - `pet.json` still points to `spritesheet.webp` - the installed atlas checksum matches the accepted project atlas - when a showcase GIF was requested, its report is `ok: true`, its QA image passes dark/light inspection, and the GIF is embedded in the final response ## Repair decisions - If only semi-transparent pixels contain the key color, clean the assembled atlas; do not regenerate poses. - If cleanup removes outline pixels, restore the backup and reduce cleanup strength. Do not add edge contraction as the first response. - If the key is also a real character color, regenerate the failing source row with a non-conflicting key instead of applying aggressive cleanup. - If the source has gradients, shadows, glow, blur, or scenery mixed into the key background, regenerate the smallest failing row. Deterministic cleanup cannot reliably infer the intended silhouette. - If one row fails identity or motion QA, repair that row through `$hatch-pet`; edge cleanup is not a substitute for visual generation repair. - If the motion is technically correct but generic, revise that state's action cue from `references/action-brief.md` and regenerate only that row. - If `waiting`, `running`, and `review` read as the same pose, clarify intention and timing before changing props or adding effects. ## Promotion After acceptance: 1. Copy the current atlas to `spritesheet-before-edge-clean.webp`. 2. Replace the project `spritesheet.webp` with the accepted cleaned candidate. 3. Re-run the installed hatch-pet atlas validator on the promoted file. 4. Copy `pet.json` and `spritesheet.webp` together to `${CODEX_HOME:-$HOME/.codex}/pets//` only when the user requested installation. 5. Compare SHA-256 checksums between project and installed atlases. 6. Report the atlas, backup, QA image, JSON report, validation result, and install path.