@pebbly/aseprite-ai-artist 0.1.0

package/rules/07-review-checklist.md

@@ -0,0 +1,51 @@
+# Review checklist
+
+Run this before telling anyone a sprite is finished. `validate` covers the
+mechanical half; the rest needs you to actually look.
+
+## Mechanical — run `validate`
+
+- [ ] No off-palette colours
+- [ ] No semi-transparent pixels
+- [ ] No isolated single pixels
+- [ ] Animation frames are tagged
+- [ ] Frame timing is not uniform across a whole cycle
+- [ ] Sprite has been saved
+
+## By eye — run `look` op `preview`
+
+- [ ] **Silhouette reads.** Recognisable as one flat shape.
+- [ ] **Value contrast carries it.** Still readable desaturated.
+- [ ] **Light is consistent.** One direction, everywhere.
+- [ ] **Ramps are ramps.** Shading hue-shifts; nothing is just "darker".
+- [ ] **Lines are clean.** Even runs, no doubled pixels, no accidental jaggies.
+- [ ] **Outline style is consistent.** One choice, applied throughout.
+- [ ] **No banding.** No long parallel stripes of adjacent ramp steps.
+- [ ] **Detail is where it matters.** The face, the weapon — not the boots.
+
+## By eye — run `look` op `ascii` when something looks subtly off
+
+The text grid is where you find the pixel that is one row too low, the run of
+3 in a line of 2s, the stray colour that survived a snap.
+
+## For animation — run `look` op `filmstrip`
+
+- [ ] Volume is consistent frame to frame
+- [ ] Height is consistent (except deliberate squash)
+- [ ] The cycle loops cleanly
+- [ ] Contact poses hold longer than pass poses
+- [ ] There is anticipation before any strong action
+
+## Before handing over
+
+- [ ] Tags named the way the engine expects (`idle`, `walk`, `attack`)
+- [ ] Exported at the size and layout the user asked for
+- [ ] Spritesheet has its JSON atlas if the engine needs one
+- [ ] Working `.aseprite` saved, not just the export
+
+## Reporting
+
+Say what you checked and what you found, not "done". If something is a
+compromise — a colour that had to move a long way, a pose you could not fit in
+the pixel budget — say that too. A user can fix a stated compromise; they cannot
+fix one you hid.

package/rules/README.md

@@ -0,0 +1,16 @@
+# Rules
+
+The pixel-art craft this project encodes. One source of truth, consumed three
+ways:
+
+- **Claude Code** reads these files directly from the plugin.
+- **Every other MCP client** reads them as `rules://` resources served by the
+  MCP server, so Codex, Gemini CLI and Cursor get the same discipline.
+- **The tools themselves** implement the mechanical parts — palette snapping,
+  hue-shifted shading, the validation checks — so an agent that never reads a
+  word of this still cannot casually break the palette.
+
+Read `rules://index` for the list, or start at `00-core-principles.md`.
+
+Changing a rule here changes behaviour everywhere. Skills reference rules by
+name rather than restating them, so a rule has exactly one place to be wrong.

package/skills/README.md

@@ -0,0 +1,29 @@
+# Skills
+
+Workflows an agent follows, in the order that catches mistakes while they are
+still cheap. Each one is a procedure, not a description.
+
+They are served three ways from this one directory:
+
+- **Claude Code** loads them as plugin skills (`/aseprite-ai-artist:pixel-draw`).
+- **Any MCP client** reads them as `skill://` resources and can invoke them as
+  MCP prompts — so Codex, Gemini CLI and Cursor get the same workflows.
+- **The server instructions** list them, so an agent knows they exist without
+  being told.
+
+| Skill | Use when |
+|-------|----------|
+| `pixel-brief` | The request is open-ended and needs decisions before drawing |
+| `pixel-new` | Starting a fresh document |
+| `pixel-palette` | Choosing, building or repairing colours |
+| `pixel-draw` | The main drawing work |
+| `pixel-shade` | Flat art needs volume |
+| `pixel-rig` | A character needs to be animatable |
+| `pixel-animate` | Building a cycle |
+| `pixel-tileset` | Level art and anything that repeats |
+| `pixel-review` | Before saying anything is finished |
+| `pixel-fix` | Editing art that already exists |
+| `pixel-export` | Handing files to a game engine |
+
+Skills reference `rules://` rather than restating craft, so a rule has exactly
+one place to be wrong.

package/skills/pixel-animate/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pixel-animate
+title: Animate a cycle
+description: Build an idle, walk, run or attack cycle from key poses, set timing that reads as motion rather than a metronome, tag it, and review it as a filmstrip. Use when a rigged sprite needs to move.
+---
+
+# Animate a cycle
+
+## Before you start
+
+The sprite must be rigged onto named layers — see `pixel-rig`. Animating a
+flattened sprite means redrawing every frame by hand.
+
+## Procedure
+
+### 1. Plan the key poses
+
+Write them out before touching a frame. For a walk:
+
+1. **Contact** — front foot lands, back foot pushing. Widest stance.
+2. **Down** — weight on the front leg, body **lowest**.
+3. **Pass** — legs together, body **highest**. The frame everyone forgets, and
+   its absence is why a walk looks like sliding.
+4. **Up** — pushing off, rising.
+
+Then mirror for the other leg: 8 frames. A 4-frame walk uses contact and pass
+per leg.
+
+Idle: 2–4 frames, a breath — chest rises a pixel, shoulders follow one frame
+later. Attack: anticipation, strike, hold, recover.
+
+### 2. Create the frames
+
+```
+frame op="add" count=7
+```
+
+### 3. Block the key poses
+
+Move limbs by moving cels, not by redrawing:
+
+```
+cel op="copy" layer="arm-near" frame=1 toFrame=3
+cel op="move" layer="arm-near" frame=3 dx=2 dy=-1
+```
+
+Redraw only where a part genuinely changes shape — a foreshortened arm, a
+bending knee.
+
+### 4. Look at the keys before adding in-betweens
+
+```
+look op="filmstrip"
+```
+
+A vision model reads only the first frame of a GIF, so the filmstrip is the
+only way to actually see the motion. Check volume and height consistency here,
+while there are four frames to fix rather than eight.
+
+### 5. Add in-betweens
+
+Only once the keys read. Spacing is your easing: poses close together read slow,
+far apart read fast.
+
+### 6. Set timing
+
+```
+frame op="set_duration" durations=[150,100,100,150,150,100,100,150]
+```
+
+Hold contact poses longer than pass poses. Uniform timing reads mechanical no
+matter how good the drawings are. Typical ranges are in `rules://05-animation`.
+
+### 7. Tag it
+
+```
+tag op="create" name="walk" from=1 to=8 direction="forward"
+```
+
+Untagged frames are unusable by a game engine. `validate` treats a multi-frame
+untagged sprite as an error.
+
+### 8. Review
+
+`look op="filmstrip"` again, then run through the animation checks in
+`rules://07-review-checklist`: consistent volume, consistent height, clean loop,
+anticipation before strong actions, light that does not move.
+
+## Related
+
+`rules://05-animation`, `rules://06-layers-and-rigging`.

package/skills/pixel-brief/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pixel-brief
+title: Plan a sprite before drawing it
+description: Turn a vague pixel-art request into a written brief — size, palette, view, light, outline style — and confirm it with the user before any pixel is drawn. Use when the request is open-ended ("make me a knight") rather than a specific edit.
+---
+
+# Plan a sprite before drawing it
+
+A request like "draw me a knight sprite" contains none of the decisions that
+determine whether the result is usable. Guessing them and drawing anyway wastes
+the user's time and yours. Five questions, one answer, then draw.
+
+## What you need to know
+
+| Decision | Why it cannot be deferred | Reasonable default |
+|----------|--------------------------|--------------------|
+| **Canvas size** | Determines how much can be shown at all | 32×32 for a character |
+| **Palette** | Choosing it later means repainting | PICO-8 (16 colours) |
+| **View** | Side-on, top-down and 3⁄4 are different drawings | 3⁄4 |
+| **Light direction** | Must be fixed before any shading | Upper-left |
+| **Outline** | Changes every edge in the sprite | Selective, dark-coloured |
+| **Destination** | A game engine wants tags and a sheet | Ask |
+
+## Procedure
+
+1. **`preflight`.** If not ready, stop and tell the user — nothing below works
+   without a live Aseprite.
+
+2. **Read what already exists.** If a sprite is open, `sprite_info` it. The
+   user's existing canvas size and palette usually answer half the questions,
+   and matching an existing project's style is almost always what they want.
+
+3. **Draft the brief.** Fill the table above from what the user said plus the
+   defaults. Do not ask about things you can reasonably infer — "a Game Boy
+   style knight" has already told you the palette and the size range.
+
+4. **Put it to the user in one message**, as decisions rather than questions:
+
+   > 32×32, PICO-8 palette, 3⁄4 view, light from upper-left, selective dark
+   > outline. Knight in plate with a sword, facing camera. Say if any of that
+   > is wrong — otherwise I'll start.
+
+   One round trip, not five. If they said nothing about a detail, they probably
+   do not care about it.
+
+5. **Ask only what genuinely blocks you.** If the sprite is for a specific game
+   and you do not know its tile size, that one is worth asking. Light direction
+   is not.
+
+6. **Record the brief** in your working notes and hold to it. Every later
+   decision either follows from the brief or is a mistake.
+
+## Then
+
+Go to `pixel-new` to create the document, or `pixel-draw` if a suitable sprite
+is already open.
+
+## Related
+
+`rules://00-core-principles` for what the sizes buy you.
+`rules://03-silhouette-and-form` for view and proportion.

package/skills/pixel-draw/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: pixel-draw
+title: Draw a sprite
+description: Draw a sprite from silhouette to finished pixels, in the order that catches mistakes while they are still cheap — block in, check the silhouette, shade, outline, verify. Use for the main body of any drawing task.
+---
+
+# Draw a sprite
+
+The order matters more than the technique. Detail added before the form is right
+just makes the wrongness harder to see and more expensive to fix.
+
+## Procedure
+
+### 1. Look before you draw
+
+`preflight`, then `sprite_info`. You need the real layer names, frame count and
+palette. Do not assume them — a wrong layer name means drawing into the user's
+finished art.
+
+### 2. Block in the silhouette
+
+One flat colour, no detail. Target the `base` layer. Everything in one `draw`
+call:
+
+```
+draw layer="base" label="block in knight" ops=[
+  { kind:"ellipse", rect:{x:12,y:4,width:8,height:8}, color:"#5f574f", fill:"#5f574f" },
+  { kind:"rect",    rect:{x:11,y:12,width:10,height:10}, color:"#5f574f", fill:"#5f574f" },
+  …
+]
+```
+
+Batch aggressively. One call is one undo step for the user; forty calls are
+forty. See `rules://03-silhouette-and-form`.
+
+### 3. Check the silhouette immediately
+
+```
+look op="preview"
+```
+
+Ask yourself the only question that matters here: **is it recognisable as one
+flat shape?** If not, fix it now. Shading a bad silhouette is wasted work.
+
+Watch for: symmetry that reads as a statue, tangents where an arm fuses into the
+torso, limbs all the same thickness.
+
+### 4. Separate the materials
+
+Replace regions of the blockout with each material's base colour — skin, metal,
+leather, cloth. Still flat. Still one `draw` call.
+
+### 5. Shade
+
+See `pixel-shade`. One shadow step, look, one light step, look. Stop there
+unless the sprite is 32px+ and genuinely needs more.
+
+### 6. Outline
+
+Pick one style from `rules://04-outlines-and-edges` and apply it consistently.
+Selective outlining — outside only — is usually right. `transform` op `outline`
+does the mechanical part; hand-place where you want it broken.
+
+### 7. Verify precisely
+
+```
+look op="ascii"
+```
+
+The text grid is where you catch the pixel one row too low and the line run of
+3 in a sequence of 2s. A preview cannot show you those.
+
+### 8. Validate and report
+
+```
+validate
+```
+
+Fix every error. Report warnings you chose not to fix, with the reason.
+
+## Batching rules
+
+- Ops run in array order, so paint fills before outlines and outlines before
+  highlights.
+- Leave `paletteLock` on. When the result says a colour moved with ΔE > 12, the
+  palette has no colour for what you asked — say so rather than turning the lock
+  off.
+- Use `label` to describe the intent; it becomes the user's undo entry.
+
+## Related
+
+`rules://00-core-principles`, `rules://02-shading-and-light`,
+`rules://03-silhouette-and-form`, `rules://04-outlines-and-edges`.

package/skills/pixel-export/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pixel-export
+title: Export game-ready assets
+description: Produce the files an engine actually consumes — spritesheets with atlases, GIFs, scaled PNGs — with the tags and layout the target needs. Use when work is finished and needs to leave Aseprite.
+---
+
+# Export game-ready assets
+
+## Ask what consumes it
+
+The target decides the format, and guessing produces files someone has to
+re-export. If you do not know, ask — it is one question.
+
+| Target | Wants |
+|--------|-------|
+| Unity | Spritesheet PNG + JSON atlas, `byTag` split |
+| Godot | Spritesheet PNG, or `.aseprite` via an importer plugin |
+| Web / canvas | Spritesheet PNG + JSON |
+| Preview for a human | GIF, or a scaled PNG |
+| Print / social | PNG at 4–8× |
+
+## Before exporting
+
+Run `pixel-review`. Exporting broken art just distributes it.
+
+Then check specifically:
+
+- **Tags exist and are named the way the engine expects** — `idle`, `walk`,
+  `attack`. `validate` errors on untagged multi-frame sprites.
+- **The reference layer is deleted or hidden**, and so is the sketch layer.
+- **Frame durations are set.** GIF and most engines read them from the file.
+
+## Exporting
+
+**Spritesheet with atlas** — what an engine usually wants:
+
+```
+export op="spritesheet" path="…/knight.png" sheetType="packed" byTag=true padding=1
+```
+
+`padding` prevents texture bleed at non-integer zoom, which shows up as a thin
+line of the neighbouring frame along a sprite's edge. Use 1 unless the engine
+says otherwise.
+
+The JSON atlas is written beside the PNG and carries per-frame rectangles and
+per-tag ranges.
+
+**Animation preview for a human:**
+
+```
+export op="gif" path="…/walk.gif"
+```
+
+**Scaled PNG** — for a store page or a README:
+
+```
+export op="png" path="…/knight@8x.png" scale=8
+```
+
+Integer scale only. Nearest-neighbour. Any other kind of resize destroys the
+thing you made.
+
+## Save the source
+
+Exporting does not save the working document.
+
+```
+sprite_manage op="save"
+```
+
+The `.aseprite` file is the asset. The PNG is a build artifact.
+
+## Report
+
+List the files you wrote, their dimensions, the frame count and the tags. That
+is what the person wiring them into the engine needs.
+
+## Related
+
+`rules://07-review-checklist`, `rules://05-animation`.

package/skills/pixel-fix/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pixel-fix
+title: Fix or iterate on existing art
+description: Change a sprite that already exists — the user's own work or your earlier output — without destroying what is already right. Use for edits, touch-ups, style corrections and "make it more X" requests.
+---
+
+# Fix or iterate on existing art
+
+Editing someone's work has a failure mode that drawing from scratch does not:
+breaking something that was already correct. The whole procedure is built around
+not doing that.
+
+## Procedure
+
+### 1. Understand what is there before changing it
+
+```
+preflight
+sprite_info
+look op="preview"
+```
+
+For a targeted edit, also `look op="ascii"` on the region. You cannot edit
+pixels precisely from a description.
+
+**Never assume layer names, frame counts or the palette.** Drawing into the
+wrong layer is the most common way an agent damages someone's file.
+
+### 2. Say what you are about to change
+
+For anything beyond a small touch-up, state the plan in one line and let the
+user stop you. Especially before: changing the palette, resizing the canvas,
+merging layers, or editing a layer you did not create.
+
+### 3. Scope the edit as tightly as you can
+
+- A **selection** limits `draw`, `recolor` and `transform` to one area.
+- A **layer** target keeps you out of everything else.
+- A **region** on `recolor` avoids touching the whole cel.
+
+Scoping is cheaper than repairing.
+
+### 4. Make the change in one call
+
+One `draw` with all its ops, one `recolor`. That is one Ctrl+Z for the user if
+they dislike it. Use `label` to describe the intent — it becomes their undo
+entry.
+
+### 5. Verify what actually changed
+
+```
+look op="diff" fromFrame=… toFrame=…
+```
+
+for animation work, or `look op="ascii"` on the region for a static edit. A
+preview shows you the result; a diff shows you the *change*, including the parts
+you did not intend.
+
+### 6. Validate and report
+
+```
+validate
+```
+
+Report what changed and what you deliberately left alone.
+
+## Interpreting vague requests
+
+| Request | Usually means |
+|---------|---------------|
+| "more contrast" | Widen the value range of the ramps, not the hue |
+| "cleaner" | Remove strays, even out line runs, merge near-duplicate colours |
+| "more detail" | Usually wrong at small sizes — ask what should read better |
+| "pop more" | Contrast against the background, or a brighter accent |
+| "less flat" | Shading exists but does not hue-shift, or has no light direction |
+| "off / uncanny" | Run `pixel-review`; name the specific cause |
+
+Reflect your reading back before acting on it. "More detail" on a 16×16 sprite
+usually means the sprite needs to be bigger, and that is worth one question.
+
+## What not to do
+
+- Do not redraw a sprite from scratch because it is easier than editing it,
+  unless the user asked for that.
+- Do not "improve" things nobody mentioned.
+- Do not widen the palette to fit a colour you chose. Say the palette lacks it.
+- Do not flatten, resize or re-index without being asked.
+
+## Related
+
+`pixel-review`, `rules://00-core-principles`.

package/skills/pixel-new/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pixel-new
+title: Create a sprite document
+description: Create a new Aseprite document with the right canvas size, colour mode, palette and layer structure, so later work does not have to fight the setup. Use when starting fresh rather than editing an existing sprite.
+---
+
+# Create a sprite document
+
+Set-up mistakes are expensive to undo: a canvas that is the wrong size means
+redrawing, and a palette chosen after the art means repainting. Get these four
+things right and the rest of the work is drawing.
+
+## Procedure
+
+1. **`preflight`.** Stop if not ready.
+
+2. **Create the canvas.**
+
+   ```
+   sprite_manage op="new" width=32 height=32 colorMode="rgb"
+   ```
+
+   - Use **RGB** unless the user wants hard palette enforcement at the file
+     level. Indexed mode makes the palette a hard constraint Aseprite itself
+     enforces — good for a strict retro target, awkward for iteration.
+   - Size to the game's grid if there is one: a 16×16 tile game wants character
+     sprites that are a multiple of 16 in at least one dimension.
+   - Leave headroom. A 32×32 canvas for a 28px-tall character gives room for a
+     weapon raise or a jump squash without a later canvas resize.
+
+3. **Set the palette before drawing.**
+
+   ```
+   palette op="preset" preset="pico8" replace=true
+   ```
+
+   Or build one: `palette op="ramp" base="#c04030" steps=5` per material. See
+   `rules://01-palette-and-color`.
+
+4. **Build the layer structure** in one batch, so it is one undo step:
+
+   ```
+   layer batch=[
+     {op:"create", name:"sketch"},
+     {op:"create", name:"base"},
+     {op:"create", name:"shading"},
+     {op:"create", name:"outline"},
+   ]
+   ```
+
+   For anything that will be animated, build the full character rig instead —
+   see `pixel-rig`. Splitting baked pixels apart later is real work.
+
+5. **Save immediately**, so the user has a file and undo has an anchor:
+
+   ```
+   sprite_manage op="save_as" path="…/knight.aseprite"
+   ```
+
+   Ask where, or put it beside whatever project the user is working in.
+
+6. **Confirm** what you made in one line: size, mode, palette, layers.
+
+## Then
+
+`pixel-draw` to block in the art.
+
+## Related
+
+`rules://01-palette-and-color`, `rules://06-layers-and-rigging`.

package/skills/pixel-palette/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pixel-palette
+title: Choose, build and repair a palette
+description: Pick a palette that fits the request, build hue-shifted ramps, or clean up a sprite whose colours have sprawled. Use when the user asks about colour, wants a specific retro look, or when validate reports off-palette colours.
+---
+
+# Choose, build and repair a palette
+
+## Choosing
+
+Match the request, in this order of preference:
+
+1. **The user named a palette or a game.** Use it. `palette op="preset"` for a
+   bundled one, `op="load"` for a file they have, or
+   `reference op="sample_palette"` to pull one out of a screenshot they gave you.
+2. **The user described an era.** "8-bit" → PICO-8. "Game Boy" → gameboy.
+   "NES" → build 12–16 colours by hand as 3–4 hues × 4 values.
+3. **The sprite is joining an existing project.** `sprite_info` an existing
+   asset and match it exactly. Consistency beats a nicer palette.
+4. **Nothing said.** PICO-8. It is 16 colours, forgiving, and reads well.
+
+`palette op="preset"` with no valid preset lists what is bundled and says that
+anything else can be loaded from a file.
+
+## Building ramps
+
+A ramp is one material's run of colours. Build them hue-shifted:
+
+```
+palette op="ramp" base="#c04030" steps=5 spread=0.55
+```
+
+Shadows come out cooler, highlights warmer — the thing that separates pixel art
+from a brightness slider. Three to five steps per material is plenty; more is
+decisions you will not use.
+
+Reuse steps across materials. Sharing the darkest colour between skin and
+leather ties the sprite together and costs nothing.
+
+## Repairing a sprawled palette
+
+Symptom: `validate` reports off-palette colours, or the sprite has ninety
+near-identical browns.
+
+1. **Diagnose:**
+
+   ```
+   palette op="analyze"
+   ```
+
+   This reports off-palette colours in the art, near-duplicate palette entries
+   (ΔE < 3 — the same colour to a viewer), unused slots and the lowest-contrast
+   pair.
+
+2. **Decide the target palette.** Either the existing one, minus the
+   near-duplicates, or a fresh one.
+
+3. **Snap the art onto it:**
+
+   ```
+   recolor op="snap" layer="…"
+   ```
+
+   Perceptual (CIELAB) nearest, applied per distinct colour in one pass. The
+   result reports exactly which colour became which and how many pixels moved,
+   so you can see whether a merge was wrong before the user does.
+
+4. **Re-check.** `palette op="analyze"` again, then `look op="preview"`. Merging
+   two colours that were doing different jobs is the risk here; look for a form
+   that has gone flat.
+
+## Contrast
+
+Value contrast carries readability, not hue contrast. Check by running
+`recolor op="desaturate"` on a copy — if the shapes stop reading in greyscale,
+the palette's values are too close, and no amount of hue will fix it.
+
+## Related
+
+`rules://01-palette-and-color`, `rules://02-shading-and-light`.