What is shader-debug?

Perfect for Graphics Agents needing advanced shader debugging capabilities for GLSL fragment shaders. shader-debug is a tool for debugging GLSL fragment shaders, enabling rendering to PNG files for visual inspection and feedback.

How do I install shader-debug?

Run the command: npx killer-skills add pthm/soup/shader-debug. It works with Cursor, Windsurf, VS Code, Claude Code, and 19+ other IDEs.

What are the use cases for shader-debug?

Key use cases include: Debugging shader output discrepancies, Inspecting shader values without simulation, Iterating on shader code for rapid visual feedback, Debugging coordinate systems and UV mapping.

Which IDEs are compatible with shader-debug?

This skill is compatible with Cursor, Windsurf, VS Code, Trae, Claude Code, OpenClaw, Aider, Codex, OpenCode, Goose, Cline, Roo Code, Kiro, Augment Code, Continue, GitHub Copilot, Sourcegraph Cody, and Amazon Q Developer. Use the Killer-Skills CLI for universal one-command installation.

Are there any limitations for shader-debug?

Requires Go runtime environment. Limited to GLSL fragment shaders. Output is PNG files only.

shader-debug

Install shader-debug, an AI agent skill for AI agent workflows and automation. Works with Claude Code, Cursor, and Windsurf with one-command setup.

SKILL.md

Readonly

Shader Debug Skill

Name: shader-debug
Availability: InStock
Author: pthm

Debug GLSL fragment shaders by rendering them to PNG files.

When to Use

Shader output doesn't look right in the game
Need to inspect shader values without running the simulation
Iterating on shader code and want quick visual feedback
Debugging coordinate systems, UV mapping, or color output

Tool Location

cmd/shaderdebug/main.go

Basic Usage

bash
1# Render a shader to PNG
2go run ./cmd/shaderdebug -shader shaders/resource.fs -out /tmp/debug.png
3
4# View the result
5open /tmp/debug.png  # macOS

Flags

Flag	Default	Description
`-shader`	`shaders/resource.fs`	Fragment shader path
`-out`	`debug.png`	Output PNG path
`-width`	512	Render width
`-height`	512	Render height

Shader Requirements

The shader must accept these uniforms (automatically set by the tool):

uniform float time; - Set to 0.0
uniform vec2 resolution; - Set to (width, height)

Standard inputs available:

in vec2 fragTexCoord; - UV coordinates (0,0 at top-left, 1,1 at bottom-right after flip)

Debugging Workflow

1. Create a minimal test shader

glsl
1#version 330
2in vec2 fragTexCoord;
3out vec4 finalColor;
4uniform vec2 resolution;
5
6void main() {
7    // Output UV as color to verify coordinates
8    finalColor = vec4(fragTexCoord.x, fragTexCoord.y, 0.0, 1.0);
9}

2. Test the pipeline

bash
1go run ./cmd/shaderdebug -shader shaders/debug_test.fs -out /tmp/uv.png

Expected: Gradient from black (top-left) to yellow (bottom-right).

3. Isolate the problem

Add intermediate outputs:

glsl
1// Debug: output distance as brightness
2float dist = length(uv - center);
3finalColor = vec4(vec3(dist), 1.0);

4. Use the Read tool to view results

Read /tmp/debug.png

The assistant can view PNG files directly and describe what it sees.

Common Issues

Shader appears all black

Check if values are in valid range [0, 1]
Verify uniforms are being set correctly
Test with debug_test.fs to verify pipeline works

Coordinates seem wrong

fragTexCoord has (0,0) at top-left after image flip
For world coordinates: vec2 worldPos = fragTexCoord * resolution;
Remember toroidal wrapping if simulating torus

Values too dark/bright

Normalize values to [0, 1] range
Use clamp() to prevent overflow
Check math for division by zero

Pre-made Debug Shaders

Shader	Purpose
`shaders/debug_test.fs`	UV coordinates as colors
`shaders/debug_circle.fs`	Single circle at center
`shaders/debug_dist.fs`	Distance from center

Example: Debug Resource Field

bash
1# Test resource shader at game resolution
2go run ./cmd/shaderdebug \
3  -shader shaders/resource.fs \
4  -out /tmp/resource.png \
5  -width 1280 -height 720
6
7# Check the output
8open /tmp/resource.png

If hotspots aren't visible:

Check radius values (might be too small relative to resolution)
Verify UV vs world coordinate usage
Test with a simple single-hotspot shader first

shader-debug — GLSL fragment shader debugging shader-debug, community, GLSL fragment shader debugging, ide skills, debugging GLSL shaders, shader-debug install, Claude Code, Cursor, Windsurf

About this Skill

Features

# Core Topics

Agent Capability Analysis

Ideal Agent Persona

Core Value

↓ Capabilities Granted for shader-debug

! Prerequisites & Limits

Browser Sandbox Environment

⚡️ Ready to unleash?