@pebbly/aseprite-ai-artist 0.1.0

package/skills/pixel-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: pixel-review
+title: Review a sprite before calling it done
+description: Run the mechanical checks and the by-eye checks, then report what you found with evidence instead of declaring success. Use before finishing any pixel-art task, and when the user asks "is this good" or "why does this look off".
+---
+
+# Review a sprite before calling it done
+
+"Done" is a claim. This is how you earn it.
+
+## Procedure
+
+### 1. Mechanical checks
+
+```
+validate
+```
+
+Reports off-palette colours, semi-transparent pixels, isolated stray pixels,
+untagged animation frames, uniform timing and unsaved state — each with a
+location where one exists.
+
+Fix every **error**. For each **warning** you do not fix, have a reason and say
+it.
+
+### 2. Look at it
+
+```
+look op="preview"
+```
+
+Work down `rules://07-review-checklist`:
+
+- **Silhouette** — recognisable as one flat shape?
+- **Value contrast** — would it survive desaturation?
+- **Light** — one direction, everywhere?
+- **Ramps** — do shadows hue-shift, or are they just darker?
+- **Lines** — even runs, no doubled pixels?
+- **Outline** — one style, applied consistently?
+- **Banding** — long parallel stripes of adjacent ramp steps?
+- **Detail placement** — spent on the face and weapon, not the boots?
+
+### 3. Look closely at anything that felt off
+
+```
+look op="ascii"
+```
+
+This is where you find the pixel one row too low and the line run of 3 in a
+sequence of 2s. If step 2 left you with "something is wrong but I cannot say
+what", this is the step that names it.
+
+### 4. For animation
+
+```
+look op="filmstrip"
+```
+
+Volume consistent? Height consistent? Does it loop? Do contact poses hold
+longer? Is there anticipation before strong actions?
+
+### 5. Report
+
+State what you checked, what you found, and what you chose not to change:
+
+> Validated clean. Silhouette reads at 1×; value contrast holds desaturated.
+> Two compromises: the plume colour snapped from `#e04a6a` to `#ff77a8`
+> (ΔE 14) because PICO-8 has nothing closer, and the far arm is 2px thick
+> rather than 3 to keep the silhouette from fusing with the torso.
+
+A user can act on a stated compromise. They cannot act on one you hid.
+
+## When the user asks "why does this look off"
+
+Run the same checks, then name the specific cause rather than listing
+possibilities. The usual answers, in order of frequency: too many colours, flat
+shading, semi-transparent pixels, mushy silhouette, uniform animation timing.
+
+## Related
+
+`rules://07-review-checklist`, and every other rule it points at.

package/skills/pixel-rig/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: pixel-rig
+title: Rig a character for animation
+description: Split a character onto named layers — head, torso, arms, legs — so it can be animated by moving cels instead of redrawing pixels. Use before animating anything, or when limbs are baked into one layer.
+---
+
+# Rig a character for animation
+
+Pixels baked into a single layer cannot be animated without redrawing them. Rig
+first; separating a finished sprite later is more work than building it split.
+
+## The standard rig
+
+Bottom to top, so nearer parts draw over farther ones:
+
+```
+arm-near     ← camera-side arm
+leg-near
+head
+torso
+arm-far      ← partly hidden by the torso; this is what sells depth
+leg-far
+shadow       ← ground contact, if the style has one
+```
+
+Add `weapon`, `cape`, `hair-front`, `hair-back` as the design needs. Keep names
+stable — every later call refers to them by name.
+
+## Building it fresh
+
+One batch, one undo step:
+
+```
+layer batch=[
+  {op:"create", name:"shadow"},
+  {op:"create", name:"leg-far"},
+  {op:"create", name:"arm-far"},
+  {op:"create", name:"torso"},
+  {op:"create", name:"head"},
+  {op:"create", name:"leg-near"},
+  {op:"create", name:"arm-near"},
+]
+```
+
+Then draw each part on its own layer from the start.
+
+## Splitting an existing sprite
+
+When the art is already baked into one layer:
+
+1. `sprite_info` to see what you have, and `look op="ascii"` to find exact part
+   boundaries. Guessing at coordinates here is how limbs get clipped.
+2. Create the rig layers (above).
+3. For each part, in one `draw` call per target layer:
+   ```
+   draw layer="head" ops=[{ kind:"blit", from:{x:12,y:4,width:8,height:8}, to:{x:12,y:4} }]
+   ```
+   `blit` copies from the source layer; `skipTransparent` keeps the copy clean.
+4. Clear the copied region from the original layer, or rename the original to
+   `flat-original` and hide it. **Prefer hiding** — if a boundary was wrong you
+   want the original still there.
+5. `look op="preview"` with the original hidden. The sprite should look
+   unchanged. If a limb lost pixels, the boundary was wrong.
+
+## Overlap matters
+
+A limb needs a pixel or two of overlap with the torso, or a gap appears the
+moment it rotates. Copy generously and let the stacking order hide the excess.
+
+## Then
+
+`pixel-animate`.
+
+## Related
+
+`rules://06-layers-and-rigging`, `rules://03-silhouette-and-form`.

package/skills/pixel-shade/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: pixel-shade
+title: Shade a sprite
+description: Add light and shadow with proper hue shifting, one step at a time, so the sprite gains form without gaining the flat-luminance look that marks generated pixel art. Use when flat art needs volume.
+---
+
+# Shade a sprite
+
+Flat shading — the same hue, darker — is the clearest signal that a sprite was
+made by moving a brightness slider. Real shading shifts hue.
+
+## The rule
+
+- **Shadows** rotate toward blue/purple and desaturate slightly.
+- **Highlights** rotate toward yellow/orange and saturate slightly.
+
+`recolor` op `shade` implements this. Use it instead of choosing darker hex
+values yourself.
+
+## Procedure
+
+1. **Fix the light direction** and state it. Upper-left is the safe default. It
+   does not move again — not across the sprite, not across animation frames.
+
+2. **Confirm the flat art is right first.** `look` op `preview`. Shading a bad
+   silhouette wastes the effort.
+
+3. **One shadow step.** Select the region away from the light, then:
+
+   ```
+   select op="rect" rect={…}
+   recolor op="shade" amount=-0.2 selectionOnly=true
+   ```
+
+   Or draw the shadow shape directly with `draw` if it needs to follow a form
+   the selection tools cannot describe.
+
+4. **Look.** `look op="preview"`. Does it read as volume, or as a stain? A
+   shadow that follows the form's cross-section reads; one that follows the
+   outline does not.
+
+5. **One light step**, on the side facing the light: `amount=0.2`.
+
+6. **Look again.** Most sprites are finished here.
+
+7. **Only if it needs it**: a deep shadow (`amount=-0.4`) in occluded crevices,
+   a specular highlight of one or two pixels on the hardest material, or
+   reflected light — a faint cool step on the shadow side's outer edge, which
+   makes metal read as metal.
+
+## Ramps
+
+If you will shade a material more than once, put its ramp in the palette:
+
+```
+palette op="ramp" base="#c04030" steps=5
+```
+
+Then draw with ramp entries directly. Reuse the darkest step across materials —
+it ties a sprite together and costs no palette slots.
+
+## Dithering
+
+Only on 32px+ and only in large flat areas. Use `bayer4`, keep the two colours
+adjacent in a ramp, and stop if it reads as noise. See
+`rules://02-shading-and-light`.
+
+## Checks
+
+- Is the light in exactly one place?
+- Do the shadows hue-shift, or are they the same hue darker?
+- Any banding — long parallel stripes of adjacent steps?
+- Any semi-transparent pixels? (`validate` will tell you.)
+
+## Related
+
+`rules://02-shading-and-light`, `rules://01-palette-and-color`.

package/skills/pixel-tileset/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: pixel-tileset
+title: Build a tileset
+description: Design seamless tiles and autotile sets, or deduplicate a hand-painted mockup into a reusable tileset, then export for Tiled or Godot. Use for level art, terrain and anything that repeats.
+---
+
+# Build a tileset
+
+Requires an extension advertising the `tileset` feature — check `preflight`
+first. Older builds answer `unsupported_command` loudly rather than doing
+nothing.
+
+## Decide the grid before anything else
+
+The tile size is the one decision everything else depends on, and it belongs to
+the game, not to the art. Ask if you do not know it. 16×16 and 32×32 are the
+common answers.
+
+## Seamless tiles
+
+A tile is seamless when its right edge continues into its own left edge, and its
+bottom into its own top.
+
+Method that works:
+
+1. Draw the tile's interior first, ignoring edges.
+2. Draw the edge pattern on one side.
+3. `look op="ascii"` the first and last columns and make them continue into each
+   other. This is exact work; do it in the text grid, not by eye.
+4. Same for top and bottom rows.
+5. Stamp the tile in a 3×3 block and `look op="preview"`. Seams show up
+   immediately when tiled; they are invisible in isolation.
+
+**Avoid a repeating feature.** A distinctive rock in the middle of a grass tile
+becomes a visible grid the moment it repeats. Keep repeating tiles low-contrast
+and put the distinctive elements in occasional variant tiles.
+
+## Autotiling
+
+A blob-47 set covers every combination of neighbours for a 4-connected terrain.
+It is 47 tiles, and hand-authoring them in the right order is where this goes
+wrong — build the terrain body first, then the edge and corner cases, then
+export with `layout="blob47"` so the exporter writes the wangset.
+
+## From a painted mockup
+
+Painting a level by hand and extracting tiles from it produces better-looking
+tilesets than authoring tiles in isolation, because you see the whole picture
+while drawing.
+
+1. Paint the mockup on a normal layer, on a canvas that is a whole number of
+   tiles in each direction. `pack` refuses otherwise rather than silently
+   losing a partial edge tile.
+2. Pack it:
+   ```
+   tileset op="pack" layer="mockup" name="terrain" tileWidth=16 tileHeight=16
+   ```
+   You get a tileset plus a tilemap layer that reconstructs the mockup exactly.
+   The mockup is **hidden, not deleted** — unhide it to compare if a tile looks
+   wrong.
+3. Read the result. `cellCount` against `tileCount` tells you how much the
+   mockup actually reused. A 400-cell mockup that yields 300 tiles was painted
+   without regard to the grid; the tool says so, and the fix is to redraw with
+   the grid visible, not to accept it.
+4. `tolerance` merges near-identical cells (per-channel difference, 0–255). It
+   is off by default because a merge changes the art: the tilemap becomes an
+   approximation of the mockup rather than a copy, and the result says how many
+   cells that affected.
+
+## Export
+
+```
+tileset op="export" layer="terrain" format="tiled" path="…/terrain.tsj"
+```
+
+Writes three files: the packed PNG, the `.tsj` tileset, and a `.tmj` map that
+uses it — so the export opens in Tiled as a level, not just an image.
+
+- `format="godot"` writes a Godot 4 `TileSet` resource (`.tres`).
+- `format="json"` writes the tile grid plus the tilemap layout, for a custom
+  engine. It states its own index convention in the file.
+- LDtk needs no exporter — it reads `.aseprite` directly, so just save the
+  document.
+
+Aseprite reserves tile index 0 for the empty tile. The exporter drops it from
+the atlas so engine indices line up, and index 0 becomes "no tile", which is
+what every engine expects.
+
+## Autotiling
+
+```
+tileset op="export" format="tiled" layout="blob47" path="…/terrain.tsj"
+```
+
+Adds a Tiled wangset for 4-connected autotiling. It assumes the 47 tiles are
+authored in **canonical blob47 order** — the 47 distinct neighbour masks in
+ascending order, after Aseprite's empty tile — and refuses if the set is
+incomplete rather than writing a wangset that autotiles wrongly. If you are not
+sure of the ordering, export `format="json"` first: it reports the
+index-to-mask mapping so you can check a few tiles by eye.
+
+## Related
+
+`rules://04-outlines-and-edges` for edge consistency.

package/templates/AGENTS.section.md

@@ -0,0 +1,33 @@
+## Pixel art in Aseprite
+
+This project has `aseprite-ai-artist` wired in as an MCP server. It draws into
+the Aseprite window that is open on this machine — not into files on disk.
+
+**Before any pixel-art work:**
+
+1. Call `preflight`. If `ready` is false, stop and tell the person. Do **not**
+   fall back to editing `.aseprite` or `.png` files directly: they would not see
+   the change in their open editor, and their next save would overwrite it.
+2. Call `sprite_info`. Layer names, frame count and palette come from the
+   document, never from assumption.
+3. Read the workflow that matches the task. The server exposes them as MCP
+   resources — `skill://pixel-draw`, `skill://pixel-animate`,
+   `skill://pixel-review` and others — and the craft rules as `rules://index`.
+   Start with `rules://00-core-principles`.
+
+**While working:**
+
+- **Batch.** One `draw` call carrying every operation is correct; forty calls
+  carrying one each is wrong. Every call is one undo step for the person.
+- **Look at your work.** After drawing, call `look` — op `preview` for the
+  overall read, op `ascii` for exact pixel positions, op `filmstrip` to review
+  an animation. A tool result saying "412 pixels changed" is not evidence that
+  the sprite is right.
+- **Keep the palette.** `draw` and `recolor` snap colours to the sprite's
+  palette by perceptual distance. If a colour you want is far from every palette
+  entry, say so and ask before widening the palette.
+- **Do not change what was not asked about.** No resizing, re-indexing,
+  flattening or overwriting without a request.
+
+**Before saying anything is finished:** call `validate`, fix every error, and
+report the warnings you chose not to fix along with the reason.