# Retro Diffusion

> Use Retro Diffusion for pixel-art image generation, img2img edits, spritesheets, and animation experiments such as platformer walk cycles, turnarounds, and action sheets from reference images.

- Skill: `gabrielmoreira/retro-diffusion` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/retro-diffusion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/retro-diffusion/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/retro-diffusion

---


# Retro Diffusion

Use this skill when the user wants to generate pixel-art images or animation sheets through Retro Diffusion, especially when the task involves reference-image-driven character work like side-view platformer walks, turnarounds, or action cycles.

## Philosophy: Match The Style To The Asset Contract

Retro Diffusion does not expose a provider-agnostic model marketplace like fal. The important control is the `prompt_style`, and each style implies a specific asset contract:

- some styles are general image models
- some are spritesheet-oriented
- some are fixed-size animation generators
- some require an input frame and work best only from neutral poses

The right way to use Retro Diffusion is:

- choose the style that matches the asset shape you want
- respect the style's size contract
- pass a clean RGB reference when using `input_image`
- treat cost checks and output capture as first-class workflow steps

**Before generating, ask:**
- Are we making a single image, a spritesheet, or an animation?
- Is this a freeform prompt, a reference-driven edit, or a starting-frame animation?
- Does the selected `prompt_style` impose a fixed frame size?
- Do we want a GIF preview, a PNG spritesheet, or both?

**Core principles**:
1. **Style first, prompt second**: in Retro Diffusion, `prompt_style` is the mode selector, not just a flavor tweak.
2. **Respect size contracts**: `animation__four_angle_walking` is a `48x48` workflow, `animation__8_dir_rotation` is `80x80`, and advanced animations should match the starting frame size.
3. **Reference cleanliness matters**: `input_image` should be RGB with no transparency, and the prompt should describe the reference rather than assume the API will infer everything.
4. **Capture the sheet, not just the preview**: for sprite work, prefer `return_spritesheet: true` so downstream analysis stays deterministic.
5. **Prompt shorter than you think**: for advanced animations, keep prompts extremely terse. The service expands action text internally, and long prompts can fail server-side even when your raw prompt looks reasonable.
6. **Treat completion as artifact-based, not CLI-message-based**: a run can succeed even if the local wrapper times out, drops the final response, or never prints a clean completion message.

## What This Skill Provides

- A portable Retro Diffusion harness bundled with the skill for:
  - text-to-image
  - img2img-style runs via `input_image`
  - multi-reference runs via `reference_images`
  - fixed-style animation and spritesheet generation
- A generic inference runner that:
  - sends requests to `POST https://api.retrodiffusion.ai/v1/inferences`
  - supports cost-only checks via `check_cost: true`
  - writes normalized run manifests and decoded outputs
- A batch runner for repeatable experiment configs
- Model/style presets for commonly useful Retro Diffusion modes:
  - `rd-pro-platformer`
  - `rd-pro-edit`
  - `rd-pro-spritesheet`
  - `rd-fast-character-turnaround`
  - `rd-plus-character-turnaround`
  - `animation-four-angle-walking`
  - `animation-8-dir-rotation`
  - `animation-walking-and-idle`
  - `rd-advanced-animation-walking`
  - `rd-advanced-animation-idle`
  - `rd-advanced-animation-attack`

## Working With Retro Diffusion

### API Shape

- Endpoint: `POST https://api.retrodiffusion.ai/v1/inferences`
- Auth header: `X-RD-Token: YOUR_API_KEY`

Outputs can include:

- `base64_images`
- `output_urls`
- `balance_cost`
- `remaining_balance`

Important operational rule:

- do not assume a run failed just because the terminal process returned no final success line
- Retro Diffusion runs can complete while the local caller reports an indeterminate state
- before retrying, check the intended output folder for:
  - new image artifacts
  - run metadata JSON
  - file modification times newer than the run start
- only classify a run as failed after artifact verification, not from missing stdout alone

Animations normally come back as transparent GIFs. Add `return_spritesheet: true` when you want a PNG sheet instead.

### Reference And Animation Guidance

For `input_image`:

- convert to RGB first
- remove transparency
- do not include the `data:image/png;base64,` prefix
- mention what the reference is in the prompt
- prefer an explicit prepared RGB reference image over silent RGBA-to-black conversion

For side-view platformer walks:

- prefer `rd_advanced_animation__walking` first when you already have a neutral starting frame
- keep `width` and `height` equal to that starting frame
- use `frames_duration` deliberately instead of taking the default
- ask for in-place locomotion if you want extractable frames instead of a traveling character
- if a large anchor behaves inconsistently, prepare a compact square reference first and retry
- successful advanced-walking runs returned transparent spritesheet PNGs rather than GIFs when `return_spritesheet: true` was set

For multi-direction walking presets:

- `animation__four_angle_walking` and `animation__walking_and_idle` are `48x48` workflows
- they are useful for broad exploration, but not as clean for direct comparison against an existing `64x64` anchor

For eight-direction turnaround experiments:

- try `animation__8_dir_rotation` first when you want a one-shot directional sheet
- remember it is fixed at `80x80`
- treat it as the first experiment, not guaranteed directional truth
- if `animation__8_dir_rotation` returns server errors or weak directions, fall back immediately to a staged `rd_pro__edit` workflow
- a dependable staged fallback is:
  - cardinals first from the isometric anchor
  - diagonals second using the same anchor plus the cardinal sheet as `reference_images`

### Prompting Guidance

Prompt like animation direction, not concept art copy:

- who the character is
- facing direction
- intended motion
- what must remain stable
- what should not happen

Good Retro Diffusion prompt components for character animation:

- identity: compact adventurer, same costume colors, same silhouette and proportions
- facing: side-facing, profile view, facing right
- motion: walk cycle in place, readable step rhythm, alternating arm swing
- stability: keep silhouette and costume consistent frame to frame
- exclusions: no camera movement, no perspective rotation, no extra props, no background

For advanced animation prompts in particular:

- prefer one or two short sentences
- avoid long descriptive prose
- avoid repeating identity details more than necessary
- keep the full prompt comfortably below `300` characters when possible

Important live-use nuance:

- "shorter" is not the same as "better"
- once you have a run that preserves character identity well, do not aggressively simplify the prompt unless you know which clauses are safe to remove
- keep the non-negotiable guardrails that lock the output:
  - facing / camera orientation such as `side-facing`
  - identity preservation such as `same costume and silhouette`
  - action disambiguation such as `bow-butt melee attack`
  - cleanup constraints such as `no background clutter`
- removing those guardrails can cause Retro Diffusion to drift into a different move family entirely, even when the starting frame and references are correct

## Scripts

- `scripts/retro_inference_run.py`
  - one Retro Diffusion run
  - image, edit, or animation/spritesheet
  - supports cost-only mode
- `scripts/retro_experiment_matrix.py`
  - run a JSON-defined experiment batch
  - useful for cross-comparing Retro Diffusion styles on the same source sprite
- `scripts/prepare_reference_image.py`
  - prepare explicit RGB reference inputs from local PNGs
  - flatten transparency to a chosen matte
  - optionally resize to a target square with nearest-neighbor scaling

## Portable Workflow

Keep project-specific artifacts in the user's working project, not inside the skill directory.

Good default layout:

- checked-in experiment contracts under a path such as `experiments/retro-diffusion/configs/`
- generated outputs under a project-owned `outputs/`, `artifacts/`, or asset-staging directory
- human-readable prompts, notes, and learnings next to the experiment docs if the project uses them

The important rule is:

- the skill provides scripts, references, and presets
- the user's project decides where prompts, configs, manifests, and generated images live

## Run Verification Workflow

When a Retro Diffusion run appears to stall, timeout, or return an ambiguous result:

1. Record the intended output directory before starting the run.
2. Launch the run once.
3. If the wrapper does not report clean completion, inspect the output directory before doing anything else.
4. Check for:
   - expected output filenames
   - non-empty PNG / GIF artifacts
   - run JSON or response JSON written by the harness
   - timestamps newer than the invocation time
5. If artifacts exist, treat the run as completed and assess quality from the returned sheet.
6. Only retry when:
   - no new artifacts were produced, or
   - the returned artifact is explicitly corrupt / incomplete for the task.

Practical rule:

- ambiguous transport state is not the same as model failure
- verify files first, retry second

## Anti-Patterns To Avoid

❌ **Anti-pattern: comparing incompatible animation styles as if they were the same task**
Why bad: a fixed `48x48` four-angle walker and a reference-driven advanced walking sheet are not equivalent outputs.
Better: compare them as different Retro Diffusion strategies, not as the same contract.

❌ **Anti-pattern: feeding transparent RGBA sprites directly into `input_image`**
Why bad: the docs say `input_image` should be RGB with no transparency.
Better: convert the input to RGB first and keep the subject on a clean flat background.

❌ **Anti-pattern: asking for “walk animation” without saying whether you want a GIF or spritesheet**
Why bad: you may get a preview format that is harder to analyze downstream.
Better: request `return_spritesheet: true` when the goal is extraction or frame comparison.

❌ **Anti-pattern: using verbose prompts with advanced animation modes**
Why bad: the backend may internally expand the action text and hit a hidden `500`-character validation limit.
Better: keep advanced-animation prompts minimal and literal.

❌ **Anti-pattern: over-simplifying a prompt after a good run**
Why bad: deleting "extra words" often deletes the exact identity and motion constraints that were keeping the model on-style.
Better: shorten carefully, but preserve the clauses that lock facing, silhouette, action type, and background behavior.

❌ **Anti-pattern: retrying immediately because the wrapper did not print a clean success message**
Why bad: Retro Diffusion may already have produced the output sheet, and an unnecessary retry wastes time, money, and confuses source-of-truth selection.
Better: inspect the target output directory and run artifacts first, then decide whether a second run is actually needed.

❌ **Anti-pattern: assuming the reference image alone will preserve style**
Why bad: `animation__any_animation` can still drift into the wrong move family or add inconsistent effects if the prompt stops reinforcing orientation and action semantics.
Better: pair the starting frame and references with a compact but explicit prompt that preserves orientation, identity, and action read.

❌ **Anti-pattern: assuming a larger isometric anchor will work better**
Why bad: larger references can be less stable than compact prepared anchors, especially in advanced animation modes.
Better: downscale the approved anchor to a compact square first, then try advanced walking.

❌ **Anti-pattern: trusting `animation__8_dir_rotation` as the canonical turnaround path**
Why bad: it can fail server-side or produce weak directional separation even at the documented `80x80` size.
Better: keep it as a cheap first probe only, and rely on staged `rd_pro__edit` when you need a dependable turnaround workflow.

❌ **Anti-pattern: ignoring the built-in frame-size contracts**
Why bad: some styles silently clamp or ignore your requested size.
Better: choose the style because its size/output format fits the task.

❌ **Anti-pattern: treating Retro Diffusion as a general-purpose video model**
Why bad: this API is about pixel-art image and animation sheet generation, not free-camera video.
Better: use it for sprite-native outputs and compare those against video-derived workflows later.

## Variation Guidance

**IMPORTANT**: Do not converge on one Retro Diffusion mode for every sprite task.

- vary between `RD_PRO`, `RD_FAST`, and advanced animation styles based on the asset contract
- vary `frames_duration` deliberately for short attack vs longer walk tests
- vary whether a run returns GIF preview or spritesheet based on the downstream need
- do not assume the best prompt for platformer walking is also the best prompt for turnarounds or idles

## References

- API and style notes: `references/api-and-styles.md`
- Animation strategy notes: `references/animation-workflows.md`
- Presets: `assets/model-presets.json`
- Prompt starters: `assets/prompt-profiles/`

## Remember

Retro Diffusion is strongest when you meet it on its own terms:

- pick the correct built-in style
- feed it a clean reference
- ask for the exact sprite artifact you need
- keep advanced-animation prompts brutally short
- prefer staged `RD Pro Edit` for dependable isometric turnaround work
- and track the result like an experiment, not a one-off prompt