agentleFS
wearekansowearekanso/agent-skills/skills/react-native-skia-shaders/SKILL.md

react-native-skia-shaders

Skill8 starsChanged 9 months agoMITView on GitHub

Comprehensive SKSL (Skia Shading Language) shader techniques for react-native-skia — ray marching, SDF modeling, procedural noise, lighting, post-processing, image filters, BackdropFilter, child shaders, gesture- and Reanimated-driven uniforms. Triggers on tasks involving Shader, RuntimeEffect, SKSL, custom visual effects, animated backgrounds, image distortion, blur, glow, glass / liquid effects, or any request to "write a shader" in a React Native or Expo app using @shopify/react-native-skia.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Always read techniques/rn-skia-integration.md: before generating any shader code — it shows the exact React component wiring (<Canvas> → …

    line 90
  2. Very specific:

    Always read techniques/sksl-vs-glsl.md: before porting a GLSL/ShaderToy snippet — the translation is not free.

    line 91
  3. Very specific:

    When the user shows you GLSL / ShaderToy code, apply these mechanical rewrites before anything else (full table in …

    line 136
  4. Distinctive:

    Every SKSL shader for react-native-skia returns a color:

    line 155
  5. Very specific:

    If you declare uniform float3 color.

    line 237
  6. Very specific:

    If a uniform is never referenced in the shader body, the compiler removes it.

    line 241
  7. Very specific:

    Use image.eval(pixelCoords) on a uniform shader image.

    line 245
  8. Distinctive:

    If you see a solid black canvas:

    line 304

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

React Native Skia Shaders

A unified skill covering 25+ SKSL shader techniques adapted for @shopify/react-native-skia. SKSL is Skia's portable shading language — a GLSL-like dialect that compiles to Metal (iOS), Vulkan/OpenGL (Android), and WebGPU/WebGL (web). Most ShaderToy / GLSL recipes translate, but the type system, entry point, coordinate system, uniform declaration, and child-shader / image sampling are different. Don't copy-paste GLSL — port it.

When to Apply

Reach for this skill when:

  • Writing or porting any SKSL shader for @shopify/react-native-skia
  • Building animated backgrounds, mesh gradients, ink/water/glass effects, particle fields
  • Distorting, blurring, or color-grading images with <Shader> + <ImageShader> or <RuntimeShader> filters
  • Composing BackdropFilter for live-blur / glassmorphism over scrolling content
  • Driving shader uniforms from gestures, Reanimated useSharedValue, or useClock
  • Debugging "compilation failed" / black-screen issues in Skia.RuntimeEffect.Make
  • Picking a performance budget that won't melt mid-tier Android phones
  • Translating a ShaderToy / GLSL snippet to SKSL

Skip this skill for: legacy react-native-svg masks, animated GIF playback, native iOS Metal / Android Vulkan shaders written outside Skia, Three.js/expo-three (those use raw GLSL with a different runtime).

Skill Structure

react-native-skia-shaders/
├── SKILL.md                          # This file — entry point & routing
├── techniques/                       # Implementation guides (read per routing table)
│   ├── rn-skia-integration.md        # Canvas, Fill, Shader, RuntimeEffect wiring
│   ├── sksl-vs-glsl.md               # Conversion cheatsheet (THE most-used file)
│   ├── uniforms-animation.md         # Reanimated, useClock, gesture-driven uniforms
│   ├── child-shaders.md              # uniform shader, ImageShader, BackdropFilter
│   ├── image-effects.md              # Blur, ColorMatrix, Displacement, RuntimeShader filter
│   ├── mobile-performance.md         # GPU budgets, profiling, fallbacks
│   ├── sksl-pitfalls.md              # Common SKSL compile errors & fixes
│   ├── sdf-2d.md                     # 2D signed distance functions
│   ├── sdf-3d.md                     # 3D signed distance functions
│   ├── ray-marching.md               # Sphere tracing with SDF
│   ├── csg-boolean-operations.md     # Smooth blends, intersections
│   ├── domain-warping.md             # Distort space with noise
│   ├── domain-repetition.md          # Infinite repetition, folding
│   ├── lighting-model.md             # Phong, Blinn-Phong, PBR-lite
│   ├── shadow-techniques.md          # Hard & soft shadows
│   ├── normal-estimation.md          # Tetrahedron technique
│   ├── ambient-occlusion.md          # SDF AO
│   ├── procedural-noise.md           # Value, Perlin, Simplex, FBM
│   ├── voronoi-cellular-noise.md     # Worley, F1/F2 distances
│   ├── color-palette.md              # Cosine palettes, Oklab, HSL
│   ├── procedural-2d-pattern.md      # Bricks, hex, truchet
│   ├── polar-uv-manipulation.md      # Polar, kaleidoscope
│   ├── fractal-rendering.md          # Mandelbrot, Julia
│   ├── sdf-tricks.md                 # Hollowing, outlines, debug viz
│   ├── post-processing.md            # Bloom, tone mapping, vignette
│   ├── anti-aliasing.md              # SDF AA, smoothstep AA
│   ├── matrix-transform.md           # Camera look-at, FOV
│   ├── texture-sampling.md           # ImageShader sampling patterns
│   ├── atmospheric-scattering.md     # Sky, fog, sunset
│   └── particle-system.md            # Stateless particles
└── reference/                        # Deep-dive math, advanced patterns
    ├── sksl-vs-glsl.md               # Full SKSL spec quick-ref
    ├── uniforms-animation.md         # Reanimated worklet patterns
    ├── ray-marching.md               # Sphere tracing math
    ├── lighting-model.md             # PBR derivations
    ├── procedural-noise.md           # Noise function theory
    └── ...

How to Use

  1. Identify the technique(s) from the Routing Table below.
  2. Always read techniques/rn-skia-integration.md before generating any shader code — it shows the exact React component wiring (<Canvas> → <Fill> → <Shader> → RuntimeEffect.Make) and how to feed uniforms.
  3. Always read techniques/sksl-vs-glsl.md before porting a GLSL/ShaderToy snippet — the translation is not free.
  4. Read the matched techniques/*.md — each contains core principles, SKSL-correct code templates, and a worked example.
  5. Follow the reference link at the bottom of each technique file if you need math derivations.
  6. Apply the Performance Budget (below) — react-native-skia runs on phones, not desktop GPUs.

Technique Routing Table

User wants to create...Primary techniqueCombine with
First-time SKSL shader, "just show me how"rn-skia-integrationsksl-vs-glsl
Port a ShaderToy / GLSL effectsksl-vs-glslrn-skia-integration
Animated background driven by timeuniforms-animationprocedural-noise, color-palette
Gesture-controlled distortionuniforms-animationdomain-warping, child-shaders
Distorted / wavy imagechild-shadersdomain-warping, image-effects
Glass / frosted / glassmorphismchild-shaders + image-effectspost-processing
Live blur over scrolling content (BackdropFilter)image-effectschild-shaders
Color grading an imageimage-effectscolor-palette
Displacement map / liquid effectimage-effects + domain-warpingprocedural-noise
Mesh gradient / fluid color blobprocedural-noisecolor-palette, domain-warping
3D objects / scenes from mathray-marching + sdf-3dlighting-model, shadow-techniques
Smooth-blended 3D shapescsg-boolean-operationssdf-3d, ray-marching
Infinite repeating patternsdomain-repetitionsdf-3d, ray-marching
Organic / warped shapesdomain-warpingprocedural-noise
Realistic lighting (Phong, PBR-lite)lighting-modelshadow-techniques, ambient-occlusion
Soft shadowsshadow-techniqueslighting-model
Surface normals from SDFnormal-estimationsdf-3d
Ambient occlusionambient-occlusionlighting-model, normal-estimation
Noise / FBM texturesprocedural-noisedomain-warping
Tiled 2D patternsprocedural-2d-patternpolar-uv-manipulation
Voronoi / cell patternsvoronoi-cellular-noisecolor-palette
Fractals (Mandelbrot, Julia)fractal-renderingcolor-palette, polar-uv-manipulation
Color grading / palettescolor-palette—
Bloom / tone mapping / glitchpost-processingchild-shaders
2D shapes / UI from SDFsdf-2dcolor-palette, anti-aliasing
Sky / fog / atmosphericatmospheric-scattering—
Stateless particles (sparks, stars)particle-systemprocedural-noise
Polar / kaleidoscopepolar-uv-manipulationprocedural-2d-pattern
Anti-aliased SDF renderinganti-aliasingsdf-2d
Camera transforms / look-atmatrix-transformray-marching
Image sampling trickstexture-samplingchild-shaders
SDF tricks / optimizationsdf-trickssdf-3d, ray-marching
"It compiles but is black" / crashessksl-pitfalls + mobile-performance—

SKSL Quick Reference (most-used translations)

When the user shows you GLSL / ShaderToy code, apply these mechanical rewrites before anything else (full table in techniques/sksl-vs-glsl.md):

GLSL / ShaderToySKSL (react-native-skia)
void mainImage(out vec4 c, in vec2 fc)vec4 main(vec2 pos) (or half4 main(float2 pos))
Implicit fragColor writereturn vec4(...);
fragCoord / gl_FragCoord.xypos (the parameter — already pixel-space, top-left origin)
iResolution.xyA uniform float2 resolution; you must pass yourself
iTimeA uniform float time; driven by useClock() or Reanimated
iMouseA uniform float2 touch; driven by Gesture.Pan()
texture(iChannel0, uv)image.eval(uv * resolution) with uniform shader image;
#version 300 es / precision highp float;Remove — SKSL has no #version
vec2, vec3, vec4Same — or float2/3/4 (interchangeable); prefer half2/3/4 for color math
mat2, mat3float2x2, float3x3 (or keep mat2/mat3 — both work)
out vec4 fragColor;Delete — main returns a vec4 instead
gl_FragCoord.xy / iResolution.xypos / resolution

Critical entry point

Every SKSL shader for react-native-skia returns a color:

uniform float2 resolution;
uniform float time;

vec4 main(vec2 pos) {
    vec2 uv = pos / resolution;     // 0..1
    vec3 col = 0.5 + 0.5 * cos(time + uv.xyx + vec3(0, 2, 4));
    return vec4(col, 1.0);
}

pos is pixel-space, top-left origin — same as gl_FragCoord.xy. Aspect-correct UVs:

vec2 uv = (2.0 * pos - resolution) / resolution.y;   // -aspect..aspect on x, -1..1 on y

Wiring it into a React component

import { Canvas, Fill, Shader, Skia, useClock } from "@shopify/react-native-skia";
import { useDerivedValue, useWindowDimensions } from "react-native";

const source = Skia.RuntimeEffect.Make(`
uniform float2 resolution;
uniform float time;
vec4 main(vec2 pos) {
    vec2 uv = pos / resolution;
    return vec4(0.5 + 0.5 * cos(time + uv.xyx + vec3(0,2,4)), 1.0);
}
`)!;

export const Cosmic = () => {
  const { width, height } = useWindowDimensions();
  const clock = useClock();                                    // ms shared value
  const uniforms = useDerivedValue(() => ({
    resolution: [width, height],
    time: clock.value / 1000,                                  // seconds
  }));
  return (
    <Canvas style={{ flex: 1 }}>
      <Fill>
        <Shader source={source} uniforms={uniforms} />
      </Fill>
    </Canvas>
  );
};

uniforms accepts a plain object or a Reanimated derived value. The object keys must exactly match the uniform names in the SKSL source. The values must be numbers or arrays of numbers — vectors are arrays (float2 → [x, y]), matrices are flat row-major arrays.

Performance Budget (mobile)

Skia on a phone is not WebGL on a desktop. Be aggressive about cost:

LimitiOS (Metal)Android (mid-tier)Notes
Ray-march steps (per pixel)≤ 80≤ 48Far below the 128 ShaderToy budget
Volume / shadow inner loops≤ 16≤ 8Each costs ~1 SDF evaluation
FBM octaves≤ 5≤ 4Mid-tier Snapdragons stutter past 4
Total inner-loop iterations / pixel≤ 500≤ 300Beyond this the GPU thread budget breaks 60fps
Canvas sizeMatch pixelRatio carefullyDownscale to ~0.75xA retina-sized full-screen shader is 3x more work than it looks
pow(), exp(), log(), sin(), cos()Cheap — use freelyCheapAvoid pow(x, 100.0) for sharp specular — use repeated *

Always test on the lowest-end target device. A shader that hits 60fps on iPhone 15 Pro will often drop to 20fps on a 2022 Pixel 6a. See techniques/mobile-performance.md for profiling.

Common SKSL Pitfalls

(Full list in techniques/sksl-pitfalls.md.)

Skia.RuntimeEffect.Make() returns null

The compile failed. Make returns null on error and does not throw. Always:

const source = Skia.RuntimeEffect.Make(sksl);
if (!source) throw new Error("SKSL compile failed");

The current public signature is Skia.RuntimeEffect.Make(sksl: string) — no error callback. If Make returns null, errors are logged to console.log by Skia itself. To diagnose, run the same SKSL in a CanvasKit playground or temporarily wrap with a smaller test shader and bisect the body.

Wrong uniform sizes → silent black

If you declare uniform float3 color; but pass color: [1, 0], the shader silently produces wrong output (sometimes black). Vector arity must match exactly: float2=2, float3=3, float4=4, float3x3=9 floats row-major.

Unused uniforms get pruned

If a uniform is never referenced in the shader body, the compiler removes it. Passing it later throws Uniform not found. Either reference the uniform (= uniform * 0.0 + …) or drop it from the JS side.

texture() doesn't exist in SKSL

Use image.eval(pixelCoords) on a uniform shader image; parameter. Coordinates are in pixels, not UVs — multiply your normalized UV by the image's natural size or by resolution before passing.

Reserved words

SKSL inherits GLSL's reserved-word list and adds a few. Don't name a variable sample, filter, input, output, texture, partition, active, common, cast, patch. Especially sample — it collides with a built-in.

Reanimated values from JS thread

Passing a Reanimated SharedValue directly to uniforms works (Skia integrates with Reanimated). Passing sharedValue.value from JS does not animate — it's captured once. Either use useDerivedValue(() => ({...})) or pass the SharedValue itself (when supported by your version).

Quick Recipes

End-to-end shader recipes assembled from technique modules.

Animated mesh gradient background

  1. Color: color-palette cosine palette
  2. Movement: domain-warping low-freq FBM
  3. Time: uniforms-animation useClock
  4. Output: rn-skia-integration <Canvas>/<Fill>/<Shader>

Glassmorphism card

  1. Backdrop: BackdropFilter wrapping a Blur(20) (image-effects)
  2. Refraction: light displacement via a child-shader with a normal-map sample
  3. Edge highlight: sdf-2d rounded rect AA outline
  4. Composite: stacked <RoundedRect> + glass shader + content

Liquid / ripple distortion over an image

  1. Source: <ImageShader> as a uniform shader
  2. Distortion: domain-warping sin/FBM displacement
  3. Driver: uniforms-animation useClock + tap position
  4. Polish: anti-aliasing bilinear sample

Stylized 2D scene

  1. Shapes: sdf-2d + sdf-tricks (layered edges)
  2. Color: color-palette + polar-uv-manipulation
  3. Polish: anti-aliasing analytic AA + post-processing vignette

Photoreal ray-marched scene (use sparingly on mobile)

  1. Geometry: sdf-3d + csg-boolean-operations
  2. Rendering: ray-marching + normal-estimation
  3. Lighting: lighting-model + shadow-techniques (soft)
  4. Atmosphere: atmospheric-scattering height fog
  5. Post: post-processing ACES tone-map + vignette

Shader Debugging Cookbook

Replace your return line with one of these to diagnose:

What to checkCodeWhat to look for
UV mappingreturn vec4(uv, 0.0, 1.0);Smooth red→yellow gradient = correct
Distance fieldreturn vec4(d > 0.0 ? vec3(0.9,0.6,0.3) : vec3(0.4,0.7,0.85), 1.0) * (0.8 + 0.2*cos(150.0*d));Concentric bands = SDF working
Normal directionreturn vec4(n * 0.5 + 0.5, 1.0);Smooth color gradients = correct
Ray-march step countreturn vec4(vec3(float(steps) / 64.0), 1.0);Red hotspots = bottleneck
Hit distancereturn vec4(vec3(t / 10.0), 1.0);Depth ramp
Time pulsereturn vec4(vec3(0.5 + 0.5 * sin(time)), 1.0);Confirms time uniform is wired
Image samplereturn image.eval(pos);Confirms <ImageShader> child is reaching the shader
Resolution checkreturn vec4(pos / resolution, 0.0, 1.0);Should be a clean 0..1 gradient

If you see a solid black canvas:

  1. Did Skia.RuntimeEffect.Make return non-null? (check immediately)
  2. Are all uniforms supplied with correct arity?
  3. Did you forget return vec4(..., 1.0) (alpha must be > 0)?
  4. Is <Fill> or another shape wrapping the <Shader>? <Shader> is a paint, not a layer — it needs something to paint.

Anti-Pattern Catalog

  • ❌ Calling Skia.RuntimeEffect.Make inside a component body — recompiles every render. Hoist to module scope.
  • ❌ Passing Date.now() as the time uniform from JS — locks the frame rate to JS scheduling. Use useClock() (worklet-driven).
  • ❌ Building uniforms as a fresh object every render without useDerivedValue — breaks Reanimated optimization.
  • ❌ A 1024×1024 ray-march on <Fill> of a full-screen Canvas on a Pixel 4a — that's ~1M pixels × 64 steps = 64M SDF evaluations per frame.
  • ❌ Mixing half and float carelessly in PBR-style math — half overflows in pow(x, 64.0) highlights.
  • ❌ Using gl_FragCoord anywhere — it doesn't exist in SKSL. Use the pos parameter.
  • ❌ Trying to read pixel neighbours in a single pass — Skia shaders are pure functions of position; multi-pass = re-render the Canvas.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.