git:20261020.a6743ad to git:20261022.1e5b402

1 added, 1 removed. Audit A to A.

---

name: pixelbolt-pixel-art

description: Make or fix pixel art - sprites, sprite sheets, tiles and tilesets, icons, game effects such as fire, smoke, water or sparks, and short frame animations - and save them as PNG, GIF, APNG or frames for a video. Use when someone asks to draw, animate, fix or export pixel art or game sprites. Pixelbolt JSON recipes, local, no account, no API key.

---

# Pixelbolt pixel art

Use this when creating pixel sprites, tiles, icons, effects or short sprite animations. Pixelbolt lives at the project root two directories above this skill's directory. Run its CLI with Node.js, or use its MCP tools if configured.

In the Claude Code plugin, the MCP tools (`pixel_help`, `pixel_validate`, `pixel_inspect`, `pixel_patch`, `pixel_render` and the rest) come with this skill. If they are missing, the plugin's server did not start: it needs Node.js 20 or later on PATH (`node --version`). Install Node.js from https://nodejs.org, then restart Claude Code.

In the portable Pixelbolt Studio build, run `.\pixelbolt` on Windows or `./pixelbolt` elsewhere from the build folder instead of `node bin/pixelbolt.js`.

**Quick effects first.** When someone asks for a ready-made looping effect (a campfire, torch, smoke puff, steam vent, explosion, magic swirl, drip, splash, waterfall, bubbling potion, honey or slime) as a file to use or share, start from the matching preset in `examples/*.fluid.json` (in the Pixelbolt folder two directories above this skill's directory), change only what they asked for (for a bigger file, use `pixel_render`'s `gif.scale`; a different canvas size also means moving the effect's obstacles and emitters, which use absolute coordinates), compile it with `pixel_compile`, look at it once with `pixel_inspect`, and export the compiled revision with `pixel_render` (`gif` for a GIF to post). Deliver that file first, then offer to tune the look or add props such as logs or stones. Don't build a new recipe around the effect, or run the full art workflow below, before the first export.

Read `docs/agent-guide.md` before creating the first recipe. Use `schema.json` for exact field names. Begin with one of the files in `examples/` if helpful.

For finished artwork, also read `docs/art-workflow.md` and the worked before/after study in `docs/art-quality-lab.md`. Establish a small art brief outside the recipe: native/display size, three silhouette landmarks, palette roles, light direction, material rules, outline treatment, action intent, contact/origin and scene role. Record the actual strengths and failures of each review. A rendered file, frame count or passing test is not evidence of artistic quality. These checkpoints do not require user permission.

Work in this order: **silhouette → large connected color shapes → material accents → authored action poses → timing → scene integration**. Do not mass-generate variants before the resting silhouette and one action read well. Use primitive geometry as a blockout; revise contours and connected color groups deliberately. Noise and extra glow cannot fix weak structure. Design different behaviors for water, fire and crystal rather than recoloring identical geometry.

1. Choose a small canvas and cohesive palette appropriate to the requested asset.

2. Write a JSON recipe in a user-appropriate output location. Use text grids and reusable symbols; reuse frames for small changes.

3. Validate with `node bin/pixelbolt.js validate <recipe>`.

4. Inspect every frame with `node bin/pixelbolt.js inspect <recipe> --out <frames.png> --native --diagnostics` and look at both sizes. Review `--view silhouette` and `--view grayscale` against the intended background; use `--animation <name> --view onion` for previous/next poses in playback order. Watch the studio/APNG too: a static sheet is not motion review. Before changing exact pixels, read them with `--grid --region x,y,w,h`. For long cycles with a repeating structure (a strobe alternating A and B frames), `--max-cells` samples can alias between phases; pick one phase with `--step 2 --offset 0` or `--offset 1`, or select frames by pattern with `--frames 'flash-*'`. `node bin/pixelbolt.js patch <recipe> --changes <changes.json>` previews a targeted edit and lists every pixel it changes, including inherited poses; add `--out <new recipe>` to save it. Use grid/mask patches for coherent shapes; dots preserve and an explicit erase character clears. Choose `scope: "frame"` when other poses must retain their current pixels; otherwise edits propagate.

5. Render with `node bin/pixelbolt.js render <recipe> --out <directory>`. Choose a fresh output directory for each iteration unless replacing your own generated output intentionally. When someone needs a file to post or embed, add `node bin/pixelbolt.js gif <recipe> --out <new.gif>` (`--scale`, `--background`) and report its `notes`: GIF drops partial alpha and rounds timing to 10 ms. For words on screen (titles, captions, counters) use the `text` operation rather than drawing letters by hand. For a video editor, check the timing first with `node bin/pixelbolt.js validate <recipe> --fps <rate>` (its `frameGrid` lists durations off the video frame grid), then use `node bin/pixelbolt.js sequence <recipe|scene> --out <new folder> --fps <rate> --size 1080p` (`--fit cover` fills the frame and crops) and pass on its `notes` and the ffmpeg command it prints. To share a folder of numbered PNG frames (a sequence, or frames from a video or effects tool) as a GIF, use `node bin/pixelbolt.js gif-frames <folder> --fps <rate> --out <new.gif>` rather than a palette generator: colours stay exact, frames get their own colour tables when they need them, and the `notes` report timing, alpha and numbering.

6. Return links to the source recipe, sheet, atlas JSON and preview, with a short integration note for the intended web app or engine.

For MCP, call `pixel_help`, then `pixel_inspect` with `{ "project": recipe }`, adding `animation`, `region` or `grid: true` as needed. Later calls take the returned `revision` instead of the full recipe. Revisions persist in the configured output directory across restarts, including unexported work; keep using the same absolute `--out` path. Fix problems with `pixel_patch` and check that only the intended pixels changed. Use `{ "paint": "frames[blink]", "value": [{ "x": 9, "y": 7, "color": "k" }] }` inside `changes` for exact canvas-coordinate corrections after all layers. `transparent` erases; palette and hex colors replace exact RGBA. The original layers stay editable, and inherited frames also receive the correction. The same changes work with the CLI patch command. Call `pixel_render` with the final revision to export; the bundle includes the patched recipe and the response previews all frames. Add `animation` to preview a sequence in playback order. The response lists key files and counts; pass `listFiles` for every file. `pixel_compile` turns a pose source or autotile template into a revision, `pixel_scene` reviews or exports a scene manifest whose assets may be revisions, and `pixel_import` converts a native PNG into a lossless recipe revision. Requests are capped at 16 MiB: send a large recipe once and reuse its revision.

Avoid gradients, subpixel geometry and antialiasing. Respect the project's requested pixel dimensions. Preserve editable source. Export at scale 1 for game assets unless the user asks for larger pixels baked into the files.

For figures in motion, use `pixelforge-poses` with `bone` limbs, `mass` bodies and grid heads, hands and props. Read `docs/art-workflow.md#structural-limbs-and-bodies` for the exact fields. Bone width profiles and ramp lighting redraw the limb at each angle. Use relative `angle`, canvas `reach` on two-bone chains, named endpoints and grid `views`; use `relight:true` on mirrors when the world light should stay fixed.

Assign rig roles and use idle/walk/run/jump/attack/hurt templates as editable starting points. In a side view, draw far limbs a ramp step darker and give paired legs the same rest angles; near limbs stay in front for the whole cycle, and `swapDepth: true` is only for front or back views. Set speed, stride, lift, bob and frame timing for the particular body; inspect reach warnings and change parameters before adding detail. `compile --expand` exposes all generated poses, and authored poses override generated names. Review silhouette, adjacent key-pose differences, planted contacts and the loop join. `inspect source.poses.json --motion run --speed 48` (MCP `pixel_inspect` with `source`, `view:"motion"`, `animation` and `speed`) reports quantitative checks and a trajectory strip. With a compiled recipe/revision, supply explicit compile metadata. The studio opens pose sources directly and offers **Motion** and **Show contacts**. Do not infer contact quality from a still sheet or claim better art from passing numerical checks alone.

Use the pose compiler for named parts, authored shape replacements, attachments and cue metadata. A pose can `mirror` an earlier pose around its origin (the anchor corner, the same reflection as `drawFrame`'s `flipX`), and a part instance can use `flipX`, so left-facing sets need no hand-mirrored copies; centre symmetric front views on the origin corner. Compiled recipes carry pose origins as frame anchors and markers as named frame points; the atlas exports them as pivots and points for game code (feet, hands, blade tips, glyph advances). Keep the pose source authoritative. Use fingerprinted overlays for approved corrections after a generator rebuild; overlays fingerprint each frame they touch, so they reapply (reported as rebased) when only other frames changed, and a changed target frame must be reviewed before creating a new overlay. Use a bounded scene manifest to review overlapping silhouettes, value hierarchy, density and persistent aftermath; give placements `anchor: "frame"` so each frame stands on its own atlas anchor, as it will in the game. PNG import can preserve a native RGB/RGBA editor correction without pretending to reconstruct drawing operations. Optional normal/emissive passes come after the base art works.

For tiles, review `--view tile` (a 3×3 repeat with doubled-edge and wrap-step evidence) and set `wrap` on frames whose drawing should continue across the edges. Author terrain as one 2×3-tile autotile template and compile it with `autotile` into 47 blob or 16 cardinal tiles; check placement with a scene `tilemap` using an autotile legend before exporting. When a tile depends on what lies around it (a wall's face on the floor below it, a cliff under an island's edge, bricks beside walls), give the legend entry `rules` with 3×3 `where` patterns, `chance` and `offset` instead of computing character maps in a script; variants take `weights`, and an autotile variant can carry its own `template` (cracked or mossy stone with the same edges). To shade, dither or rewrite a composed room, draw it inside one recipe with the `tilemap` operation and follow it with those operations. Share a palette between recipes with `"palette": { "$ref": "palette.json" }`, cycle water or lights with per-frame `palette` overrides instead of redrawing, give a layer its own `palette` when only that layer should flash or cycle (a strobe on a glow that shares a key with the panel border), and use `remap` on stamps and copies for color variants; on frame copies `remap` swaps exact colours, such as a whole pose turned white for a hit flash. `copy` reuses a rectangle of a symbol or an earlier frame; `outline` adds a one-pixel outline around every visible pixel drawn so far in the same frame or layer. Set `sheet.trim` to pack only visible pixels in game atlases; the exported runtime's `drawFrame` honors trim offsets, anchors and flipping.

- Craft operations help once the forms are right. Use `dither` for transitions and bands, such as a sky, a ground or a shading band limited to one colour with `over`; avoid dithering whole surfaces. For organic patches (moss, rubble, grass) use `pattern: "value"` with a `scale`: seeded smooth noise that draws clumps, not speckle, and keeps `density` as the share drawn. Declare `ramps` (palette keys from dark to light, or in the shared palette file) and shade with the `shade` operation, scene `shade` placements and `lighting.mode: "ramp"`: shadows and light then move colours along their own ramps and never leave the palette, wherever they fall. Where a Bayer grid would show over a large area or in a fade, use `pattern: "noise"` with a fixed `seed`: raising `density` across frames then dissolves pixels in one order without flicker. Use `outline` with `position: "inside"` and `directions` for rim lights along the lit edges, and outside `directions` for a drop line or shadow. `rewrite` rules grow structured detail where you point them, such as moss on exposed tops or a crack from a seed pixel; fix `seed`, `chance` and `limit`, and inspect the result, because rules add noise as easily as structure. When diagnostics count `corners` or `strays` in rotated, rewritten, compiled or imported frames, preview `{"cleanup": "frames[name]", "value": {"corners": true}}` with `patch`, read every changed pixel, and keep deliberate corners, eyes and sparks; in hand-drawn art most of them are intentional. In pose sources, `rotate` turns a part by any angle into an editable symbol and `tween` builds eased in-betweens; inspect rotated symbols at native size and redraw a part for key poses where rotation loses its shape. For particle effects, write a `pixelforge-fx` source (`pixel_help` topic `fx`) and compile it: give each material its own motion and shapes, keep counts low enough to read, and check the loop and the dissolve in playback. For fire, smoke, steam, explosions, magic swirls, water, honey or slime that should move like a fluid, start from one of the twelve `examples/*.fluid.json` presets (`pixel_help` topic `fluid`) and tune it (`viscosity` for thick liquids, `yield` for ones that hold a shape): the simulation supplies the motion, and the `look` layers decide which palette colours each density, temperature, speed or depth becomes. Check one-shots at 1× and end empty, and inspect looping results with diagnostics so the loop boundary stays quiet.

+ Craft operations help once the forms are right. Use `dither` for transitions and bands, such as a sky, a ground or a shading band limited to one colour with `over`; avoid dithering whole surfaces. For organic patches (moss, rubble, grass) use `pattern: "value"` with a `scale`: seeded smooth noise that draws clumps, not speckle, and keeps `density` as the share drawn. Declare `ramps` (palette keys from dark to light, or in the shared palette file) and shade with the `shade` operation, scene `shade` placements and `lighting.mode: "ramp"`: shadows and light then move colours along their own ramps and never leave the palette, wherever they fall. Where a Bayer grid would show over a large area or in a fade, use `pattern: "noise"` with a fixed `seed`: raising `density` across frames then dissolves pixels in one order without flicker. Use `outline` with `position: "inside"` and `directions` for rim lights along the lit edges, and outside `directions` for a drop line or shadow. `rewrite` rules grow structured detail where you point them, such as moss on exposed tops or a crack from a seed pixel; fix `seed`, `chance` and `limit`, and inspect the result, because rules add noise as easily as structure. When diagnostics count `corners` or `strays` in rotated, rewritten, compiled or imported frames, preview `{"cleanup": "frames[name]", "value": {"corners": true}}` with `patch`, read every changed pixel, and keep deliberate corners, eyes and sparks; in hand-drawn art most of them are intentional. In pose sources, `rotate` turns a part by any angle into an editable symbol and `tween` builds eased in-betweens; inspect rotated symbols at native size and redraw a part for key poses where rotation loses its shape. For particle effects, write a `pixelforge-fx` source (`pixel_help` topic `fx`) and compile it: give each material its own motion and shapes, keep counts low enough to read, and check the loop and the dissolve in playback. Give an impact one strong shape before the scatter: a one- or two-frame flash, then an even `outward` `ring` (a shockwave) or an arc of streaks drawn with `face` that cool through `tint`, children `from` the sparks `when: "floor"` where they land, and smoke drawn `behind` that fades by shrinking rather than dither speckle. `duration: {"from": 40, "to": 110, "ease": "in"}` front-loads the timing, and `cue` marks the hit frame as an exported point for game code (docs/art-workflow.md#particle-effects). For fire, smoke, steam, explosions, magic swirls, water, honey or slime that should move like a fluid, start from one of the twelve `examples/*.fluid.json` presets (`pixel_help` topic `fluid`) and tune it (`viscosity` for thick liquids, `yield` for ones that hold a shape): the simulation supplies the motion, and the `look` layers decide which palette colours each density, temperature, speed or depth becomes. Check one-shots at 1× and end empty, and inspect looping results with diagnostics so the loop boundary stays quiet.

For lit scenes, derive normal passes with a `pixelforge-normals` source (`{ "format": "pixelforge-normals", "version": 1, "recipe": "lamp.json" }`, compiled like any source) rather than painting every direction by hand. It rounds each shape from its silhouette and stays aligned with the colour recipe; add `detail` only for textured surfaces. Light the result from both sides in a scene before trusting it, and correct rims and overlapping parts with `patch`: keys are keypad digits leaning 30° (`5` faces the viewer) and `q w e a d z x c` leaning 60°. Godot and Unity read normals with +Y up; tell the user to flip the green channel on import (docs/game-integration.md).

Advisory findings are prompts to inspect, not commands to delete pixels. Exempt intentional holds, eyes, sparks, literal colors and alpha blends in the brief. Keep original assets and failed comparisons. If asked for a named game's quality level, make original art and report what the visible evidence supports; do not equate new features or automated tests with matching that game's art direction.