agent-sprite-forge

---
name: agent-sprite-forge
description: Generate game-ready 2D sprite sheets, transparent PNG frames, and animated GIFs from natural-language prompts using the Codex agent skill $generate2dsprite.
triggers:
  - generate a 2D sprite
  - create a sprite sheet
  - make a pixel art animation
  - use generate2dsprite to create
  - create an animated GIF from a prompt
  - generate a sprite bundle with cast projectile impact
  - make a four-direction walk sprite sheet
  - create game assets from a text prompt
---

# Agent Sprite Forge

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Agent Sprite Forge is a Codex agent skill (`$generate2dsprite`) that turns natural-language prompts into game-ready 2D pixel-art assets. The agent plans the asset, calls Codex's built-in image generation, then runs a deterministic local Python post-processor to clean up backgrounds, split frames, align cells, and export transparent PNGs and animated GIFs.

---

## How It Works

1. **Agent plans** the sheet layout, frame count, view angle, and action type.
2. **Codex generates** the raw sprite sheet image (built-in image generation — no external API needed).
3. **Local post-processor** (`generate2dsprite.py`) performs:
   - Magenta (`#FF00FF`) chroma-key background removal
   - Frame splitting based on grid layout
   - Bounding-box extraction and alignment
   - Rescaling
   - Transparent PNG and animated GIF export

---

## Installation

### macOS / Linux

```bash
git clone https://github.com/0x0funky/agent-sprite-forge.git
cd ./agent-sprite-forge
python3 -m pip install -r ./requirements.txt
mkdir -p ~/.codex/skills
cp -R ./skills/generate2dsprite ~/.codex/skills/generate2dsprite

Windows PowerShell

git clone https://github.com/0x0funky/agent-sprite-forge.git
cd .\agent-sprite-forge
python -m pip install -r .\requirements.txt
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force `
  ".\skills\generate2dsprite" `
  "$env:USERPROFILE\.codex\skills\generate2dsprite"

Start a new Codex session after installation so the skill is loaded cleanly.

Python Dependencies

Pillow
numpy

Install manually if needed:

pip install Pillow numpy

---

Repository Layout

agent-sprite-forge/
  requirements.txt
  skills/
    generate2dsprite/
      SKILL.md
      agents/
        openai.yaml          # Codex agent config
      references/
        modes.md             # Asset type / mode reference
        prompt-rules.md      # Prompt authoring rules
      scripts/
        generate2dsprite.py  # Local post-processor

---

Invoking the Skill

In a Codex session, use $generate2dsprite in your prompt. The agent reads SKILL.md, plans the asset, generates the sheet, then calls the local script.

Basic invocation pattern

Use $generate2dsprite to create <description>.

---

Prompt Examples by Asset Type

Idle / Creature

Use $generate2dsprite to create a 3x3 idle for an ultimate earth titan.

Use $generate2dsprite to create a golden divine boar 2x2 idle animation.

Character Attack

Use $generate2dsprite to create a side-view lightning knight attack animation.

Use $generate2dsprite to create Omegamon attack and right-move animation assets.

Spell Bundle (Cast + Projectile + Impact)

Use $generate2dsprite to create a fire mage cast animation with projectile and impact.

Use $generate2dsprite to create a wizard spell bundle with cast, projectile, and impact sprites.

Use $generate2dsprite to create a fireball projectile loop and a matching explosion impact.

Four-Direction Walk Sheet (top-down RPG)

Use $generate2dsprite to create a top-down 4x4 player_sheet for a wandering young samurai
with a red scarf and short katana. Make a four-direction walk sprite sheet with 4 frames
per direction. Row order: down, left, right, up. Same character, same outfit, same
proportions, same pixel scale in every frame. Solid #FF00FF background. Each frame must
fit fully inside its cell, with clear margin on all sides. Retro JRPG pixel-art style.

FX / Summon Effect

Use $generate2dsprite to create a side-view summon entrance effect for a thunder wolf spirit.

Reference Image → Sprite

Attach or reference an image in your Codex session:

Use $generate2dsprite to create this male character teaching animation.

Use $generate2dsprite — make an animation of this crocodile playing with the stone in its hand.

Full Playable Game (One-Shot)

Use $generate2dsprite to create a 2D side-scrolling game similar to Mega Man. It should
include attack mechanics, map elements, and all essential features. Design everything and
create all assets using this skill. It must be an actually playable game with a cyberpunk
story setting.

---

What the Post-Processor Produces

For a typical sprite sheet, the output directory contains:

File	Description
raw-sheet.png	Original image from Codex generation
raw-sheet-clean.png	After chroma-key removal
sheet-transparent.png	Full sheet with transparency
frame-00.png, frame-01.png, …	Individual extracted frames
animation.gif	Assembled animated GIF
prompt-used.txt	The exact prompt sent to generation
pipeline-meta.json	Grid layout, frame count, frame size metadata

For player walk sheets, additional per-direction outputs are generated:

File	Description
strip-down.png	Horizontal strip for down direction
strip-left.png	Horizontal strip for left direction
strip-right.png	Horizontal strip for right direction
strip-up.png	Horizontal strip for up direction
down.gif	Animated GIF for down walk
left.gif	Animated GIF for left walk
right.gif	Animated GIF for right walk
up.gif	Animated GIF for up walk

---

Running the Post-Processor Directly

If you have a raw sheet image and want to run post-processing manually:

# Example: split a 3x3 sheet and export transparent frames + GIF
from PIL import Image
import numpy as np

def remove_magenta(img: Image.Image, tolerance: int = 30) -> Image.Image:
    """Replace #FF00FF background with transparency."""
    rgba = img.convert("RGBA")
    data = np.array(rgba, dtype=np.int32)
    r, g, b, a = data[..., 0], data[..., 1], data[..., 2], data[..., 3]
    mask = (
        (r > 255 - tolerance) &
        (g < tolerance) &
        (b > 255 - tolerance)
    )
    data[..., 3] = np.where(mask, 0, a)
    return Image.fromarray(data.astype(np.uint8), "RGBA")

def split_sheet(sheet_path: str, cols: int, rows: int, output_dir: str):
    """Split a sprite sheet into individual transparent frame PNGs and a GIF."""
    import os
    os.makedirs(output_dir, exist_ok=True)

    sheet = Image.open(sheet_path).convert("RGBA")
    total_w, total_h = sheet.size
    frame_w = total_w // cols
    frame_h = total_h // rows

    frames = []
    for row in range(rows):
        for col in range(cols):
            left = col * frame_w
            top = row * frame_h
            cell = sheet.crop((left, top, left + frame_w, top + frame_h))
            clean = remove_magenta(cell)
            idx = row * cols + col
            out_path = os.path.join(output_dir, f"frame-{idx:02d}.png")
            clean.save(out_path)
            frames.append(clean)
            print(f"Saved {out_path}")

    # Export animated GIF
    gif_path = os.path.join(output_dir, "animation.gif")
    if frames:
        frames[0].save(
            gif_path,
            save_all=True,
            append_images=frames[1:],
            loop=0,
            duration=100,  # ms per frame
            disposal=2,
        )
        print(f"Saved {gif_path}")

# Usage
split_sheet("raw-sheet.png", cols=3, rows=3, output_dir="./output")

---

Asset Types and Modes

Reference skills/generate2dsprite/references/modes.md for the full list. Common modes:

Mode	Description
idle	Looping idle animation (e.g., 3x3 idle)
attack	Attack action frames
walk / player_sheet	Four-direction walk sheet (top-down RPG)
spell_bundle	Cast + projectile + impact as separate sheets
unit_bundle	Character unit with multiple action strips
combat_bundle	Full combat set: idle, attack, hit, death
projectile	Single-action projectile loop
impact / explosion	Impact / explosion FX sheet
fx_sheet	General visual effects sheet

---

Prompt Authoring Rules

From skills/generate2dsprite/references/prompt-rules.md:

• Specify view angle: side-view, top-down, isometric, front-facing
• Specify grid layout: e.g., 3x3, 2x4, 1x6 (columns × rows)
• Name the action: idle, attack, walk, cast, death
• Use magenta background: always specify solid #FF00FF background for clean chroma-key removal
• Describe style: retro JRPG pixel-art, 16-bit, 32x32, 64x64
• Keep character consistent: add Same character, same outfit, same proportions, same pixel scale in every frame
• Set margins: Each frame must fit fully inside its cell, with clear margin on all sides

Good prompt structure

Use $generate2dsprite to create a [view] [grid] [action] for [character description].
[Style notes.] [Consistency notes.] Solid #FF00FF background.
Each frame must fit fully inside its cell, with clear margin on all sides.

---

Tips for Best Results

Situation	Recommendation
Large creature / boss	Use 3x3 idle or 3x3 attack
Small spell or projectile	Use 1x4, 2x2, or 2x3
Top-down RPG player	Use player_sheet mode, specify row order explicitly
Spell with phases	Use spell_bundle — agent generates cast, projectile, impact as separate assets
Reference image → sprite	Attach the image in Codex, describe the desired action
Inconsistent frames	Add "Same character, same outfit, same proportions, same pixel scale in every frame" to prompt
Clipped sprites	Add "Each frame must fit fully inside its cell, with clear margin on all sides"
Commercial use	Use original characters or IP you control

---

Troubleshooting

Skill not found after install

Restart the Codex session. The skill directory must exist at ~/.codex/skills/generate2dsprite/ before the session starts.

ModuleNotFoundError: No module named 'PIL'

pip install Pillow

Magenta not fully removed / fringing

The default tolerance is 30. If pink fringing remains around edges, increase it in the post-processor call, or add anti-aliasing: none, hard pixel edges to your generation prompt.

Frames misaligned or wrong count

Explicitly state the grid in the prompt (e.g., 3x4 sheet, 3 columns, 4 rows). Ambiguous layouts cause the agent to guess.

GIF has no transparency

Ensure the chroma-key step runs before GIF assembly. The transparent frames must be RGBA mode. If using disposal=2, confirm Pillow version ≥ 9.0.

Generated image not game-proportional

Add explicit pixel dimensions to the prompt: each frame 64x64 pixels, total sheet 192x192.

---

License

MIT — see LICENSE.