
shader-skills
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add gokayfem/shader-skills.
Contents
Discovered from sourceSkills 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
- Target. State the image: subject, camera and framing, dominant forms, materials, light, motion.
- 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, usereferences/research-studies.mdto select the representation and a visible test of its behavior. - Assemble from the library. Find building blocks with
python3 scripts/glsl_tools.py search <words>orreferences/library-index.md, and call them by name. Do not paste or re-derive library code; it is tested. Runpython3 scripts/glsl_tools.py examples <exactName>to locate direct calls and debug views. Userg -n -w <symbol>within the relevant world directory for host-side callers. - First image fast. Coordinates, background, one primitive, one light. Then add the debug views.
- Refine in order: proportions, composition, material separation, lighting, atmosphere, color, antialiasing, performance.
- Bundle and check.
python3 scripts/glsl_tools.py bundle shader.glsl -o out.glslinlines exactly the functions used.python3 scripts/glsl_tools.py check out.glsllints it and compiles it with glslangValidator when installed. Fix every error, then deliverout.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 is2.0 / iResolution.y. - Scene contract:
vec2 map(vec3 p)returnsvec2(distance, materialId).raymarch,calcNormal,softShadow,calcAOandsdfThicknessall use it. - Debug:
#define DEBUG_MODE 0with 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 (tonemapAgXby default, per AA sample), then the average, thenlinearToSrgbonce, thenditherTPDF. - Distances: respect the
@exact/@bound/@approxtags. If a deformation pushes Lipschitz above 1, divide the distance or lower thestepScaleofraymarch.
Hard rules (these break Shadertoy/WebGL)
- No
#versionline, no custom uniforms, nogl_FragColor/texture2D/iGlobalTime. - No
?:on structs. Usevec2(distance, id)orif. - Write float literals:
2.0 * PI,clamp(x, 0.0, 1.0). - No
fract(sin(...) * 43758.5453)hashes. Usehash12/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.checkreports a sine hash as an error. - Guard NaN sources:
atan(0, 0),powof negatives,sqrtof negatives,normalize(vec3(0)). - Keep
dFdx/fwidthout of non-uniform branches and loops, or use an explicit pixel size.
Reference routing
Read only what the task needs:
| File | Read when |
|---|---|
references/subject-routing.md | starting from a subject ("a jellyfish", "mountains"); maps formal names to subjects |
references/library-index.md | choosing functions: every library function with signature, exactness and uses |
references/sdf-library-guide.md | modeling: exactness tiers, blends, neighbor-checked repetition, deformation limits, WebGL pitfalls |
references/rendering-pipeline.md | lighting rigs, shadows/AO, sky and fog, volumes, tonemapping, AA, performance |
references/noise-use-cases.md | choosing Perlin/value/simplex/cellular noise, fBm/ridged/billow/warp/hybrid recipes, game use cases and primary-source code links |
references/procedural-buildings.md | parcel IDs, building massing, setbacks/roofs, facade filtering, city repetition and game integration |
references/terrain-production.md | terrain representations, designed valleys, slope/altitude materials, tracing limits, chunks and LOD |
references/research-studies.md | optics, null geodesics, streamline engraving, reaction-diffusion, terrain caching and offline playback |
references/frame-budgets.md | diagnosing low FPS, GPU timing, foliage culling, half-resolution shafts, cache invalidation, streaming budgets and adaptive resolution |
references/vegetation-habitats.md | placing tree groves, wet-bank species and understory from shared fields |
references/world-rendering.md | kelp forests, sponges, shipwrecks, tides, foliage detail, room radiosity and full-world source navigation |
references/water-quality.md | high-quality ocean/coastal water, wave derivatives, Fresnel/refraction/absorption, foam, presets and engine-side upgrades |
references/material-sampling.md | breaking up tiled materials while preserving authored trim, layer masks, and relief |
references/shader-workflow.md | planning a complex shader end to end; review checklist |
references/composition-and-debugging.md | the image reads poorly, or something is visually wrong |
references/formula-cookbook.md | multi-step recipes: modular cell lattices, terrain synthesis, organic composition |
references/formula-code-couples-sdf.md | equation-to-code for organic and modular SDF features |
references/formula-code-couples-terrain.md | heightfields, density fields, accumulation, atmosphere |
references/formula-code-couples-materials.md | masks, 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_MODEswitches 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