/pixel-art

name: pixel-art
description: "Pixel art w/ era palettes (NES, Game Boy, PICO-8)."
version: 2.0.0
author: dodo-reach
license: MIT
metadata:
  hermes:
    tags: [creative, pixel-art, arcade, snes, nes, gameboy, retro, image, video]
    category: creative
    credits:
      - "Hardware palettes and animation loops ported from Synero/pixel-art-studio (MIT) — https://github.com/Synero/pixel-art-studio"
origin: aggregated
source_license: MIT
source_repo: NousResearch/hermes-agent
source_url: https://github.com/NousResearch/hermes-agent/tree/main/skills/creative/pixel-art
language: en

Pixel Art

Convert any image into retro pixel art, then optionally animate it into a short MP4 or GIF with era-appropriate effects (rain, fireflies, snow, embers).

Two scripts ship with this skill:

• `scripts/pixel_art.py` — photo → pixel-art PNG (Floyd-Steinberg dithering)
• `scripts/pixel_art_video.py` — pixel-art PNG → animated MP4 (+ optional GIF)

Each is importable or runnable directly. Presets snap to hardware palettes when you want era-accurate colors (NES, Game Boy, PICO-8, etc.), or use adaptive N-color quantization for arcade/SNES-style looks.

When to Use

• User wants retro pixel art from a source image
• User asks for NES / Game Boy / PICO-8 / C64 / arcade / SNES styling
• User wants a short looping animation (rain scene, night sky, snow, etc.)
• Posters, album covers, social posts, sprites, characters, avatars

Workflow

Before generating, confirm the style with the user. Different presets produce very different outputs and regenerating is costly.

Step 1 — Offer a style

Call `clarify` with 4 representative presets. Pick the set based on what the user asked for — don't just dump all 14.

Default menu when the user's intent is unclear:

clarify(
    question="Which pixel-art style do you want?",
    choices=[
        "arcade — bold, chunky 80s cabinet feel (16 colors, 8px)",
        "nes — Nintendo 8-bit hardware palette (54 colors, 8px)",
        "gameboy — 4-shade green Game Boy DMG",
        "snes — cleaner 16-bit look (32 colors, 4px)",
    ],
)

When the user already named an era (e.g. "80s arcade", "Gameboy"), skip `clarify` and use the matching preset directly.

Step 2 — Offer animation (optional)

If the user asked for a video/GIF, or the output might benefit from motion, ask which scene:

clarify(
    question="Want to animate it? Pick a scene or skip.",
    choices=[
        "night — stars + fireflies + leaves",
        "urban — rain + neon pulse",
        "snow — falling snowflakes",
        "skip — just the image",
    ],
)

Do NOT call `clarify` more than twice in a row. One for style, one for scene if animation is on the table. If the user explicitly asked for a specific style and scene in their message, skip `clarify` entirely.

Step 3 — Generate

Run `pixel_art()` first; if animation was requested, chain into `pixel_art_video()` on the result.

Preset Catalog

| Preset | Era | Palette | Block | Best for | |--------|-----|---------|-------|----------| | `arcade` | 80s arcade | adaptive 16 | 8px | Bold posters, hero art | | `snes` | 16-bit | adaptive 32 | 4px | Characters, detailed scenes | | `nes` | 8-bit | NES (54) | 8px | True NES look | | `gameboy` | DMG handheld | 4 green shades | 8px | Monochrome Game Boy | | `gameboy_pocket` | Pocket handheld | 4 grey shades | 8px | Mono GB Pocket | | `pico8` | PICO-8 | 16 fixed | 6px | Fantasy-console look | | `c64` | Commodore 64 | 16 fixed | 8px | 8-bit home computer | | `apple2` | Apple II hi-res | 6 fixed | 10px | Extreme retro, 6 colors | | `teletext` | BBC Teletext | 8 pure | 10px | Chunky primary colors | | `mspaint` | Windows MS Paint | 24 fixed | 8px | Nostalgic desktop | | `mono_green` | CRT phosphor | 2 green | 6px | Terminal/CRT aesthetic | | `mono_amber` | CRT amber | 2 amber | 6px | Amber monitor look | | `neon` | Cyberpunk | 10 neons | 6px | Vaporwave/cyber | | `pastel` | Soft pastel | 10 pastels | 6px | Kawaii / gentle |

Named palettes live in `scripts/palettes.py` (see `references/palettes.md` for the complete list — 28 named palettes total). Any preset can be overridden:

pixel_art("in.png", "out.png", preset="snes", palette="PICO_8", block=6)

Scene Catalog (for video)

| Scene | Effects | |-------|---------| | `night` | Twinkling stars + fireflies + drifting leaves | | `dusk` | Fireflies + sparkles | | `tavern` | Dust motes + warm sparkles | | `indoor` | Dust motes | | `urban` | Rain + neon pulse | | `nature` | Leaves + fireflies | | `magic` | Sparkles + fireflies | | `storm` | Rain + lightning | | `underwater` | Bubbles + light sparkles | | `fire` | Embers + sparkles | | `snow` | Snowflakes + sparkles | | `desert` | Heat shimmer + dust |

Invocation Patterns

Python (import)

import sys
sys.path.insert(0, "/home/teknium/.hermes/skills/creative/pixel-art/scripts")
from pixel_art import pixel_art
from pixel_art_video import pixel_art_video

# 1. Convert to pixel art
pixel_art("/path/to/photo.jpg", "/tmp/pixel.png", preset="nes")

# 2. Animate (optional)
pixel_art_video(
    "/tmp/pixel.png",
    "/tmp/pixel.mp4",
    scene="night",
    duration=6,
    fps=15,
    seed=42,
    export_gif=True,
)

CLI

cd /home/teknium/.hermes/skills/creative/pixel-art/scripts

python pixel_art.py in.jpg out.png --preset gameboy
python pixel_art.py in.jpg out.png --preset snes --palette PICO_8 --block 6

python pixel_art_video.py out.png out.mp4 --scene night --duration 6 --gif

Pipeline Rationale

**Pixel conversion:** 1. Boost contrast/color/sharpness (stronger for smaller palettes) 2. Posterize to simplify tonal regions before quantization 3. Downscale by `block` with `Image.NEAREST` (hard pixels, no interpolation) 4. Quantize with Floyd-Steinberg dithering — against either an adaptive N-color palette OR a named hardware palette 5. Upscale back with `Image.NEAREST`

Quantizing AFTER downscale keeps dithering aligned with