Create and debug procedural GLSL shaders with a tested library, SDF raymarching, terrain, water, clouds and ready-to-run Shadertoy examples.

GitHub stars
460

Install

/plugin install shader-skills@shader-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add gokayfem/shader-skills.

Contents

Discovered from source

Skills 1

Shader Art Coding

Treat shader work as visual engineering: start from the intended image, choose the smallest mathematical model that can produce it, build it in inspectable stages, and verify each stage with a debug view.

Workflow

  1. Target. State the image: subject, camera and framing, dominant forms, materials, light, motion.
  2. Route. Consult the example guide for working sources and visual checks. Pick the rendering model and starting template from references/subject-routing.md: 2D distance fields (posters, icons, patterns), SDF raymarching (objects, characters), heightfield marching (landscapes), volume integration (clouds, smoke, fire). For optical mechanisms, orbital light paths, vector-field prints or evolving patterns, use references/research-studies.md to select the representation and a visible test of its behavior.
  3. Assemble from the library. Find building blocks with python3 scripts/glsl_tools.py search <words> or references/library-index.md, and call them by name. Do not paste or re-derive library code; it is tested. Run python3 scripts/glsl_tools.py examples <exactName> to locate direct calls and debug views. Use rg -n -w <symbol> within the relevant world directory for host-side callers.
  4. First image fast. Coordinates, background, one primitive, one light. Then add the debug views.
  5. Refine in order: proportions, composition, material separation, lighting, atmosphere, color, antialiasing, performance.
  6. Bundle and check. python3 scripts/glsl_tools.py bundle shader.glsl -o out.glsl inlines exactly the functions used. python3 scripts/glsl_tools.py check out.glsl lints it and compiles it with glslangValidator when installed. Fix every error, then deliver out.glsl.

Run the scripts from this skill's directory. They need only Python 3.

Conventions

  • Coordinates: vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;, so one pixel is 2.0 / iResolution.y.
  • Scene contract: vec2 map(vec3 p) returns vec2(distance, materialId). raymarch, calcNormal, softShadow, calcAO and sdfThickness all use it.
  • Debug: #define DEBUG_MODE 0 with 0 final, 1 distance field, 2 normals, 3 ids, 4 steps, 5 masks, 6 lighting terms.
  • Color pipeline: light in linear and decode picked colors with srgbToLinear. Then exposure, then the tonemap (tonemapAgX by default, per AA sample), then the average, then linearToSrgb once, then ditherTPDF.
  • Distances: respect the @exact / @bound / @approx tags. If a deformation pushes Lipschitz above 1, divide the distance or lower the stepScale of raymarch.

Hard rules (these break Shadertoy/WebGL)

  • No #version line, no custom uniforms, no gl_FragColor / texture2D / iGlobalTime.
  • No ?: on structs. Use vec2(distance, id) or if.
  • Write float literals: 2.0 * PI, clamp(x, 0.0, 1.0).
  • No fract(sin(...) * 43758.5453) hashes. Use hash12 / hash22 / hash33 (integer PCG). Replace them even when porting with "keep the look": the sine hash's exact pattern already differs between GPUs, and a PCG hash on the same integer cell ids gives the noise the same look. check reports a sine hash as an error.
  • Guard NaN sources: atan(0, 0), pow of negatives, sqrt of negatives, normalize(vec3(0)).
  • Keep dFdx / fwidth out of non-uniform branches and loops, or use an explicit pixel size.

Reference routing

Read only what the task needs:

FileRead when
references/subject-routing.mdstarting from a subject ("a jellyfish", "mountains"); maps formal names to subjects
references/library-index.mdchoosing functions: every library function with signature, exactness and uses
references/sdf-library-guide.mdmodeling: exactness tiers, blends, neighbor-checked repetition, deformation limits, WebGL pitfalls
references/rendering-pipeline.mdlighting rigs, shadows/AO, sky and fog, volumes, tonemapping, AA, performance
references/noise-use-cases.mdchoosing Perlin/value/simplex/cellular noise, fBm/ridged/billow/warp/hybrid recipes, game use cases and primary-source code links
references/procedural-buildings.mdparcel IDs, building massing, setbacks/roofs, facade filtering, city repetition and game integration
references/terrain-production.mdterrain representations, designed valleys, slope/altitude materials, tracing limits, chunks and LOD
references/research-studies.mdoptics, null geodesics, streamline engraving, reaction-diffusion, terrain caching and offline playback
references/frame-budgets.mddiagnosing low FPS, GPU timing, foliage culling, half-resolution shafts, cache invalidation, streaming budgets and adaptive resolution
references/vegetation-habitats.mdplacing tree groves, wet-bank species and understory from shared fields
references/world-rendering.mdkelp forests, sponges, shipwrecks, tides, foliage detail, room radiosity and full-world source navigation
references/water-quality.mdhigh-quality ocean/coastal water, wave derivatives, Fresnel/refraction/absorption, foam, presets and engine-side upgrades
references/material-sampling.mdbreaking up tiled materials while preserving authored trim, layer masks, and relief
references/shader-workflow.mdplanning a complex shader end to end; review checklist
references/composition-and-debugging.mdthe image reads poorly, or something is visually wrong
references/formula-cookbook.mdmulti-step recipes: modular cell lattices, terrain synthesis, organic composition
references/formula-code-couples-sdf.mdequation-to-code for organic and modular SDF features
references/formula-code-couples-terrain.mdheightfields, density fields, accumulation, atmosphere
references/formula-code-couples-materials.mdmasks, palettes, lighting terms, polish, motion

Choose examples and visual checks across the complete template and multipass collection. For a creation or redesign, open the closest implementation. For a repair, compare the failing stage with its working counterpart. For an explanation, trace the relevant function and its caller. For a performance request, compare the same view and settings before and after. Use supplementary examples for specific features and check the assumptions they share with the primary example. For combinations, the guide includes worked inlet, engraved emblem, cached forest and translucent swimmer examples. Read the actual debug branches and use the test that isolates the feature being changed. For persistent state, trace the writer, the sampler, and the first frame after reset. For a visual deliverable, inspect a render at the requested size and a diagnostic that exposes the main failure mode. Report the example used, what you adapted and what you observed. Identify any check you could not run.

For two-pass requests deliver both buffers and their channel bindings. Build the offline viewer with scripts/build_viewer.py to review motion and diagnostic views.

Output expectations

When writing a shader:

  • Deliver the bundled, paste-ready Shadertoy code with mainImage(out vec4 fragColor, in vec2 fragCoord).
  • Avoid textures unless the user provides them.
  • Include DEBUG_MODE switches and name the art controls as constants at the top.
  • End with a short tuning guide: which constants control scale, softness, color, light and motion.
  • Say whether the shader was compile-checked, and how.
  • For buildings/terrain/water, separate implemented features from engine-side upgrades. Do not call a heightfield a cave generator, a material window a modeled recess, or a procedural foam/caustic mask a fluid/light simulation.
  • For quality requests, state the target and budget, expose presets/debug views, and inspect rendered output. Annotate important template presets with // @variant QUALITY=3 (or another defined integer macro) so CI compiles and renders them. Preserve horizon/shore contact and temporal filtering before adding detail.

When improving an existing shader:

  • Identify its rendering model and bottlenecks.
  • Preserve its intent and interface.
  • Fix correctness first, then readability, visual quality and speed.
  • Call out risky changes (coordinate scale, material ids, loop counts).

Sponsors

Details

Marketplace
gokayfem/shader-skills
Category
Development