Pixel Art Studio

Pixel Art Studio

Self-contained studio: you author a build script that draws every pixel with scripts/pixelstudio.py (Pillow only), render a preview, look at it with your own eyes, critique, fix, repeat. That see→critique→fix loop is the entire quality engine — never skip it. You are the artist; the library is just your hand.

Requirement: python3 -c "import PIL" — if missing, pip3 install --user pillow.

The Loop

1. Brief — decide canvas size, palette (with a hard color budget), style, outline

rule, light direction. Consult references/patterns.md + references/palettes.md, and check references/learned/INDEX.md for a studied style that matches.

1. Build script — create pixel-art//build.py in the working directory.

The script is the artwork's source of truth: it regenerates everything on each run. Parametrize shapes (positions, squash, frame offsets) instead of hardcoding every pixel twice — animation frames become function calls.

```python import sys; sys.path.insert(0, "/Users/game/Projects/.claude/skills/pixel-art-studio/scripts") from pixelstudio import Sprite, PALETTES, ramp, mix

BODY = ramp("#38b764", 5) # hue-shifted 5-step ramp from a base color s = Sprite(32, 32, palette=BODY + ["#1a1c2c", "#f4f4f4"])

def drawslime(squash=0): # parametric → reuse for every frame s.ellipse(6, 12 + squash, 25, 27, BODY[0]) # darkest first s.ellipse(6, 11 + squash, 24, 26, BODY[2], only="opaque") # restack lighter, shifted to light s.outline(BODY[0], where="inside") # selout drawslime()

s.preview("preview.png", scale=10) # LOOK at this file s.stats() # and read these numbers ```

1. Run — cd pixel-art/ && python3 build.py
2. LOOK — Read preview.png (plus s.save_silhouette() / s.zoom() when unsure).

Critique against the checklist in references/validations.md, point by point, honestly.

1. Fix — edit build.py, rerun. Minimum 2–3 loop passes before showing the user.
2. Deliver — export master PNG at 1x and a display scale (4–8x), GIF/spritesheet

if animated, then open the output files (user preference).

Work at true pixel size always; scale is an export-time concern and integer only.

API — scripts/pixelstudio.py

Colors everywhere: "#hex" | (r,g,b[,a]) | palette index (int) | None = erase. Most ops accept only= to clip: a color (paint only over that color), "opaque", "empty" — this is the masking system; the shifted-shape shading recipe in references/techniques.md builds on it.

| Area | Calls | |---|---| | Canvas | Sprite(w, h, palette=None, snap=True) · s.layer(name) · s.frame(i) · s.use(frame=, layer=) | | Draw | px line rect(fill=) circle(cx,cy,r,fill=) (pixel-perfect) ellipse polygon contour fill(x,y) clear get(x,y) paste_png | | Pixel-art ops | outline(c, where="outside"/"inside") · mirror_x mirror_y · shift(dx,dy,wrap=) · replace(old,new) · dither(box,c1,c2,mix,pattern) · gradient_dither(box,colors) · noise(box,c,density,seed) | | Color | ramp(base, steps, hue_shift) · mix(c1,c2,t) · PALETTES · s.set_palette(p, remap=) · s.to_palette(p, dither=) · s.quantize(n) | | Cleanup (gen/messy art) | s.harden_alpha(threshold, steps) · s.despeckle(min_cluster) · s.dedupe_colors(tol) · s.dehalo() · s.clean(palette=, max_colors=, ...) · s.before_after(path) | | Animation | s.add_frame(copy=True) · s.set_duration(ms, frames) · s.tag(name, from, to, direction) · s.copy_cel(layer, from_frame, to_frames, link=) · s.del_frame | | Inspect | s.preview(path, scale, grid=, labels=) · s.zoom(path, x0,y0,x1,y1) · s.save_silhouette(path) · s.stats() · s.save_swatch(path) · s.used_colors() | | Export | s.save_png(path, frame, scale, bg) · s.save_gif(path, scale, tag, bg) · s.save_spritesheet(path, layout, scale, padding) (+engine JSON) · s.save_project / Sprite.load_project / Sprite.from_png(path, scale="auto", strip_bg=) |

Knowledge routing

| Task | Read | |---|---| | Any new artwork (sizes, chibi/heroic/tall-tactical proportions, silhouette-first order, tiles) | references/patterns.md | | Color ramps, shading, dithering, AA, outlines, textures | references/techniques.md | | Animation (frame counts, timing, puppeting, oversized attack cells, stable pivots) | references/animation.md | | Humanoid characters (2 arms + 2 legs) — full movement set (walk/slash/thrust/spellcast/shoot/hurt) | references/lpc.md + scripts/lpc.py — assemble frames onto the LPC universal sheet (engine-ready layout) | | Palette choice, budgets, presets, learned palettes | references/palettes.md | | Export formats, engines (Unity/Godot/Phaser) | references/export.md | | Cleaning AI-generated / messy art, palette-locking, the hybrid pipeline | references/cleanup.md | | Known failure modes — read before finalizing | references/sharp_edges.md | | Per-iteration critique checklist | references/validations.md | | Studied styles from user-provided art | references/learned/INDEX.md |

Learning from user-provided art

When the user sends a pixel-art file to learn from (เรียนรู้/ศึกษาไฟล์นี้):

Persistence rule: learning changes the skill project itself. Resolve ` to the directory containing this SKILL.md and write durable knowledge only inside that directory. The caller's working directory, ./pixel-art/, clipboard paths, and _study/` are source or temporary analysis locations; they are not the knowledge base. Never leave a completed study only in those locations.

1. python3 /scripts/study.py [--save-palette ]

→ emits _study/ with zoom.png, swatch.png, silhouette.png, report.json.

1. Read zoom.png and swatch.png — the report gives numbers (true size, palette, ramps,

dither %, outline darkness); your eyes extract the techniques: cluster shapes, AA placement, where dither sits, how ramps map onto forms, outline behavior on the light side.

1. Write a study card /references/learned/NNN-.md from

/references/learned/TEMPLATE.md — record pixel-level observations and imperative rules, not vibes.

1. Add one line to /references/learned/INDEX.md in the same change.
2. If the lesson generalizes beyond one visual style (animation, export, validation, cleanup,

etc.), also update the relevant /references/*.md rule file and Knowledge routing.

1. --save-palette makes the palette available forever as Sprite(palette="");

verify that the saved palette data is also under ``, not beside the input file.

1. Before finishing, verify every newly learned durable file resolves under ``.

When later creating art in a studied style: open the matching card and follow its rules.

Hybrid pipeline — from generated/messy art (the "B" path)

When the user wants pixel art from an image model (codex-imagegen, SD+LoRA, FLUX, PixelLab export, a screenshot, or any messy PNG), this skill is the deterministic cleanup + lock + animate layer. Use references/cleanup.md for the full playbook. One command does the whole import→clean:

python3 /scripts/pixelpipe.py  --strip-checker --max-colors 24 --display 6
# lock to a shared game palette for cross-asset consistency:
python3 /scripts/pixelpipe.py  --palette my_game
# learn the style while cleaning:
python3 /scripts/pixelpipe.py  --strip-checker --study knight_style

It recovers the true grid (block-sampling for sloppy upscales), strips baked-in checkerboards, hardens alpha, despeckles, dedupes colors, locks the palette, and emits clean.png + a regenerable build.py you keep editing. After cleaning, switch back to the normal Loop (edit/animate/palette-swap deterministically) — that's where the skill beats the generator.

Conventions

• Artworks live in ./pixel-art// (build.py + all outputs together).
• Never hand-edit exported PNGs — edit build.py and rerun.
• Randomness only via noise(seed=) — renders must be deterministic.
• Deliverables get opened when done; report includes the 1x master path.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Gamezxz
• Source: Gamezxz/pixel-art-studio
• License: MIT
• Homepage: https://gamezxz.github.io/pixel-art-studio/

Install and usage instructions live in the source repository linked above.