pxforge-splash-to-model — Claude Code skill: setup and features
pxforge-splash-to-model is a Claude Code skill that turns splash art into a SpriteKiln YAML model. It runs when you supply a character image to generate a model, sprite or animations.
MIT ★ 177 updated 2026-11-12
npx skills add LucasJRamos/spritekiln --skill pxforge-splash-to-model -a claude-codeWhat pxforge-splash-to-model does
The skill converts character splash art into a SpriteKiln specification file. It keeps the character recognizable at a low 64-pixel resolution across eight viewing angles. The pipeline begins with reference preparation using python -m pxforge ref prep, stripping background noise and capturing proportions and distinct traits inside the YAML brief section.
From there, the agent maps hue-shifted palettes and adjusts a humanoid base mesh. It iterates on the geometry until silhouette camera-corrected IoU reaches at least 0.65 via python -m pxforge ref compare. Hair, head shapes, and accessories are fitted through kit modules before generating full eight-direction review sheets.
Operation requires Python and the pxforge package. If the reference image has a busy or textured background, transparent cutout generation relies on the optional rembg dependency installed via the splash extra.
What it helps with
- convert 2D splash art into a SpriteKiln model
- build legible 64 px silhouettes across 8 directions
- extract color ramp palettes from character artwork
- verify model proportions against splash art using IoU
Example prompts for the agent
- Here is
knight_splash.png, build a SpriteKiln character model from it - Convert this concept art
hero.pnginto an 8-direction 64 px sprite spec
How to install pxforge-splash-to-model
1Skills CLI (Vercel)
npx skills add LucasJRamos/spritekiln --skill pxforge-splash-to-model -a claude-code2Manually: put the files in place
~/.claude/skills/pxforge-splash-to-model/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pxforge-splash-to-model/
1Skills CLI (Vercel)
npx skills add LucasJRamos/spritekiln --skill pxforge-splash-to-model -a codex2Manually: put the files in place
.agents/skills/pxforge-splash-to-model/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add LucasJRamos/spritekiln --skill pxforge-splash-to-model -a cursor2Manually: put the files in place
.cursor/skills/pxforge-splash-to-model/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install LucasJRamos/spritekiln .claude/skills/pxforge-splash-to-model2Manually: put the files in place
.github/skills/pxforge-splash-to-model/SKILL.md1Skills CLI (Vercel)
npx skills add LucasJRamos/spritekiln --skill pxforge-splash-to-model -a gemini-cli2Platform CLI
gemini skills install https://github.com/LucasJRamos/spritekiln --path .claude/skills/pxforge-splash-to-modelManually: put the files in place
.devin/skills/pxforge-splash-to-model/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pxforge-splash-to-model
How to install pxforge-splash-to-model in Claude Code?
Run npx skills add LucasJRamos/spritekiln --skill pxforge-splash-to-model -a claude-code. You can also place the configuration directly into ~/.claude/skills/pxforge-splash-to-model/SKILL.md.
What does pxforge-splash-to-model do?
It translates 2D character artwork into a SpriteKiln YAML specification. The workflow optimizes silhouette proportions and palettes for eight-direction 64-pixel sprites.
What is required to run pxforge-splash-to-model?
It requires Python and the pxforge module in your environment. Processing images with busy backgrounds requires the rembg dependency installed via the splash extra.
Source text
SKILL.md · MIT
---
name: pxforge-splash-to-model
description: Turn an original splash or concept art into a SpriteKiln model (spec YAML) faithful to the art and legible at 64 px in 8 directions. Use when the user provides a character image and asks for its model, sprite or animations. (Folder name kept for projects that link to it; same as the spritekiln skill.)
---
# From a splash art to a model
Goal: capture the character's **identity** (silhouette, proportions, striking shapes, palette), not the
brush strokes. At 64 px only what is big and contrasted survives. Read [workflow.md](workflow.md),
[modeling.md](modeling.md) and [spec.md](SPEC.md) first.
## 1. Prepare the reference
```
python -m pxforge new <name> --extends --ref <path/splash.png> # <specs>/characters/<name>/ with splash.png; a humanoid
# extends the template (drop --extends to copy it)
python -m pxforge ref prep <specs>/characters/<name>/splash.png # -> splash_ref/: cutout.png, cutout_pitch38.png,
# palette.yaml, ref.json (proportions)
```
- Look at the original splash **and** `cutout.png`. The background is removed from the border inwards, so
flat, gradient and vignetted backgrounds work, and openings such as the gap between the legs stay
transparent. If it cut wrong: try `--tol` 4–15 (colour step, default 9), ask for a PNG with
transparency, or install the `splash` extra (rembg) for busy backgrounds.
- Decide which **direction** the art shows (front = `s`, 3/4 front = `se`/`sw`, profile = `e`/`w`).
## 2. Write the brief (top of the spec)
Before any geometry, fill `brief:` while looking at the image:
```yaml
brief:
summary: one sentence on who this is and how they carry themselves
reference: splash.png (seen from se)
proportions: "head = 1/4 of the height; shoulders 1.6x the hips; short legs"
head: "high ponytail past the shoulders, side-swept fringe, soft jaw, pointed chin; eyes only (face: minimal)"
must_keep: [3-6 traits that identify the character from afar]
simplify: [what will vanish or merge at 64 px]
palette_notes: [dominant materials and colours]
```
At most 5–6 `must_keep`. Small ornaments become a colour spot or vanish. Exaggerate what is iconic (hat,
weapon, hair, cape): at 64 px, exaggeration is fidelity. The head is never a detail to drop: with stylized
proportions it is about a fifth of the sprite. `head` says what the splash's hair and face are, in the terms
of the head and hair kits, and how much face the project's style (`face`) shows.
## 3. Palette
`splash_ref/palette.yaml` has colour families with hue-shifted ramps ready (`fam1`, `fam2`...). Copy it to
the project's palettes folder as `<name>.yaml`, **rename** the ramps (skin, cloth, hair, metal...), drop
background or noise families and merge near-identical ones. Adjust with
`python -m pxforge palette ramp "#hex" --steps 5`. 3–6 materials plus one emissive is ideal. In the spec:
`palette: [gothic, ../../palettes/<name>.yaml]` (gothic brings the `fx_*` ramps and basics).
## 4. Blockout
Start from a template (`humanoid`, or `side_humanoid` for a side view) or a similar spec. Over a base, give
only the keys that change (`bones: {torso_rot: {pos: ...}}`, `ik: {leg_L: {lengths: [...]}}`):
1. **World scale:** total height 1.6–2.0; adjust the pelvis height (`torso_rot.pos`) and the IK lengths.
2. **Big masses:** torso, hips and legs as ellipsoids and cones; the head's size with the `head` bone
scale (its shape and the hair come in step 5).
3. `pose --dirs all` and `ref compare <spec> <splash> --dir <dir>`.
4. Iterate until the **camera-corrected IoU ≥ 0.65** in the art's direction and no band hint is large.
Each silhouette is scaled to its own bounding box, so a hat tip, a raised weapon or a flared hem moves
the whole comparison: when an extremity changes, read the overlay on the sheet, not only the number.
`ref compare` squashes the splash by cos(pitch) like the game camera sees a front view; against the raw
splash the IoU tops out near 0.56, so do not chase raw numbers. The hints say at which height the sprite
is too wide or too narrow: fix the part at that height. Do not chase IoU above ~0.85; the splash has its
own perspective and pose, and legibility matters more.
## 5. Striking shapes and materials
First the **head and the hair**, as `brief.head` says: fit the `head` kit (`jaw`, `chin`, `width`) and a
hair kit (`hair`, `ponytail`, `bun`) with their params, or model them yourself ([modeling.md](modeling.md),
"Heads, faces and hair"). Look at them with `pose --focus head --dirs all` next to the splash's face.
Then one `must_keep` at a time (horns = `tube`), adding its entry to `review.keep` as you go
([spec.md](SPEC.md): the parts or materials that show the trait, and the directions where it must). A weapon, shield, helmet, hood, hat, cape, belt or pouch
starts from a kit (`spritekiln kits`; `use:` with its params, recoloured through materials); model your own
only when no kit comes close. After each one: `pose --dirs all`. Check the **8 directions**, not only the
art's; invent what the splash does not show, coherently, and record the decision in `brief`.
## 6. Final comparison and review
```
python -m pxforge ref compare <spec> <splash> --dir <dir> # -> out/compare_<dir>.png + .json
python -m pxforge review <spec> --ref <splash> --ref-dir <dir> [--bg <game floor>] [--tint <scene light>]
```
Open the comparison sheet (reference | sprite | silhouette overlay | 8 directions | palettes) and the review
sheet. `ref compare` also says where the sprite's colour departs from the splash's at the same height ("bands
20-30% to 40-50%: render #2a2f3a is much darker than the reference #8a2030"): a coat in the wrong colour, a
sprite far darker than the art. A splash is painted under its own light, so treat these as places to look, not
numbers to match. Then an art-direction pass ([art-direction.md](art-direction.md)); apply the high-priority
fixes.
## 7. Animate
With the model approved, follow [animation.md](animation.md). The personality of the splash (heavy, agile,
arrogant) must show in the idle and in the timing of the attack.
## Pitfalls
- A splash with a dynamic pose (raised leg, raised weapon): compare against a similar animation frame
(`--anim attack --frame 2`) instead of the rest pose.
- A cropped splash (no feet): the IoU is meaningless; compare only the proportions of the visible part and
say so.
- A weapon bigger than the body: keep it out of the comparison (note it in the brief) and check margins in
QA.
## More
Reference files in this folder: [workflow.md](workflow.md), [style.md](style.md), [SPEC.md](SPEC.md), [modeling.md](modeling.md), [animation.md](animation.md), [art-direction.md](art-direction.md), [recipe.md](recipe.md).
© LucasJRamos · MIT · LucasJRamos/spritekiln