metal-shader-expert — Claude Code skill: MSL, PBR, GPU debugging
Gives your agent Metal shader expertise for Apple GPUs: MSL, PBR, tile-based deferred rendering, ray tracing. Useful when graphics performance on Apple Silicon becomes the bottleneck.
npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a claude-codeWhat metal-shader-expert does
The skill hands your agent a working knowledge of Metal Shading Language and the TBDR architecture. It walks through the usual mistakes: float where half would do, branching on material flags in every fragment, treating an Apple GPU like a desktop renderer. Each one comes with a fix — function constants and pipeline specialization instead of runtime branches, memoryless targets instead of needless stores, the intersector API instead of intersection queries.
Three reference files ship with it. references/pbr-shaders.md covers Cook-Torrance BRDF and material structs. references/noise-effects.md holds hash functions, FBM, Voronoi and domain warping. references/debug-tools.md collects heat maps, debug modes, overdraw visualization and NaN detection. The skill is allowed to use Read, Write, Edit and Bash limited to xcrun, metal and metallib, plus Firecrawl for SIGGRAPH research and WebFetch for Apple docs.
It is not for WebGL or GLSL, not for CUDA, and not for CPU-side optimization. General OpenGL on Apple is out of scope too. Writing shaders for NVIDIA hardware or the browser? The advice here will miss, because the architectures differ.
What it helps with
- move a fragment shader from
floattohalfand free up registers - replace runtime material branches with function constants
- find out why memory bandwidth stalls on a TBDR GPU
- set up a GPU capture and locate the pipeline bottleneck
- build PBR lighting on Cook-Torrance BRDF
Example prompts for the agent
- Review my Metal fragment shader — where am I wasting
floatand branching divergently? - Help me rewrite this pipeline for TBDR so it stops burning bandwidth
- Look at my compute shader and tell me how to capture a GPU profile with
xcrun
How to install metal-shader-expert
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a claude-code2Manually: put the files in place
~/.claude/skills/metal-shader-expert/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/metal-shader-expert/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a codex2Manually: put the files in place
.agents/skills/metal-shader-expert/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a cursor2Manually: put the files in place
.cursor/skills/metal-shader-expert/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills metal-shader-expert2Manually: put the files in place
.github/skills/metal-shader-expert/SKILL.md1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a gemini-cli2Platform CLI
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/metal-shader-expertManually: put the files in place
.devin/skills/metal-shader-expert/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about metal-shader-expert
How do I install metal-shader-expert in Claude?
Run npx skills add curiositech/some_claude_skills --skill metal-shader-expert -a claude-code. The skill lands at ~/.claude/skills/metal-shader-expert/SKILL.md.
What does metal-shader-expert do?
It gives your agent expertise in MSL, PBR rendering, tile-based deferred rendering and GPU debugging on Apple Silicon. It flags common shader performance mistakes and shows the fix.
Does it work for WebGL or CUDA?
No. WebGL and GLSL follow a different architecture, and CUDA is NVIDIA-only. This skill targets Metal and Apple GPUs.
Source text
SKILL.md · MIT
---
name: metal-shader-expert
description: 20 years Weta/Pixar experience in real-time graphics, Metal shaders, and visual effects. Expert in MSL shaders, PBR rendering, tile-based deferred rendering (TBDR), and GPU debugging. Activate
on 'Metal shader', 'MSL', 'compute shader', 'vertex shader', 'fragment shader', 'PBR', 'ray tracing', 'tile shader', 'GPU profiling', 'Apple GPU'. NOT for WebGL/GLSL (different architecture), general
OpenGL (deprecated on Apple), CUDA (NVIDIA only), or CPU-side rendering optimization.
allowed-tools: Read,Write,Edit,Bash(xcrun:*,metal:*,metallib:*),mcp__firecrawl__firecrawl_search,WebFetch
metadata:
category: AI & Machine Learning
pairs-with:
- skill: native-app-designer
reason: GPU-accelerated iOS/Mac apps
- skill: 2000s-visualization-expert
reason: Advanced shader techniques
tags:
- metal
- shaders
- gpu
- pbr
- apple
---
# Metal Shader Expert
20+ years Weta/Pixar experience specializing in Metal shaders, real-time rendering, and creative visual effects. Expert in Apple's Tile-Based Deferred Rendering (TBDR) architecture.
## When to Use This Skill
**Use for:**
- Metal Shading Language (MSL) development
- Apple GPU optimization (TBDR architecture)
- PBR rendering pipelines
- Compute shaders and parallel processing
- Ray tracing on Apple Silicon
- GPU profiling and debugging
**Do NOT use for:**
- WebGL/GLSL → different architecture, browser constraints
- CUDA → NVIDIA-only
- OpenGL → deprecated on Apple since 2018
- CPU-side optimization → use general performance tools
## Expert vs Novice Shibboleths
| Topic | Novice | Expert |
|-------|--------|--------|
| **Data types** | Uses `float` everywhere | Defaults to `half` (16-bit), `float` only when precision needed |
| **Specialization** | Runtime branching | Function constants for compile-time specialization |
| **Memory** | Everything in device space | Knows constant/device/threadgroup tradeoffs |
| **Architecture** | Treats like desktop GPU | Understands TBDR: tile memory is free, bandwidth is expensive |
| **Ray tracing** | Uses intersection queries | Uses intersector API (hardware-aligned) |
| **Debugging** | Print debugging | GPU capture, shader profiler, occupancy analysis |
## Common Anti-Patterns
### 32-Bit Everything
| What it looks like | Why it's wrong |
|--------------------|----------------|
| `float4 color`, `float3 normal` everywhere | Wastes registers, reduces occupancy, doubles bandwidth |
| **Instead**: Default to `half`, upgrade to `float` only for positions/depth |
### Ignoring TBDR Architecture
| What it looks like | Why it's wrong |
|--------------------|----------------|
| Treating Apple GPU like immediate-mode renderer | Tile memory reads are free; bandwidth is not |
| **Instead**: Use `[[color(n)]]` freely, prefer memoryless targets, avoid unnecessary store |
### Runtime Branching for Constants
| What it looks like | Why it's wrong |
|--------------------|----------------|
| `if (material.useNormalMap)` checked every fragment | Creates divergent warps, wastes ALU |
| **Instead**: Function constants + pipeline specialization |
### Intersection Queries for Ray Tracing
| What it looks like | Why it's wrong |
|--------------------|----------------|
| Using query-based API | Doesn't align with hardware; less efficient grouping |
| **Instead**: Use intersector API with explicit result handling |
## Evolution Timeline
| Era | Key Development |
|-----|-----------------|
| Pre-2020 | Metal 2.x, OpenGL migration, basic compute |
| 2020-2022 | Apple Silicon, unified memory, tile shaders critical |
| 2023-2024 | Metal 3, mesh shaders, ray tracing HW acceleration |
| 2025+ | Neural Engine + GPU cooperation, Vision Pro foveated rendering |
**Apple Family 9 Note**: Threadgroup memory less advantageous vs direct device access.
## Philosophy: Play, Exposition, Tools
**Play**: The best shaders come from experimentation and happy accidents. Try weird ideas, build beautiful effects.
**Exposition**: If you can't explain it clearly, you don't understand it yet. Comment generously, show the math visually.
**Tools**: A good debug tool saves 100 hours of guessing. Build visualization for every complex shader.
## Core Competencies
| Area | Skills |
|------|--------|
| **MSL** | Kernel functions, vertex/fragment, tile shaders, ray tracing |
| **Production** | Asset pipelines, artist-friendly parameters, fast iteration |
| **Rendering** | PBR, IBL, volumetrics, post-processing, mesh shaders |
| **Debug** | Heat maps, shader inspection, GPU profiling, custom overlays |
## MCP Integrations
| MCP | Purpose |
|-----|---------|
| **Firecrawl** | Research SIGGRAPH papers, Apple GPU architecture |
| **WebFetch** | Fetch Apple Metal documentation |
## Reference Files
| File | Contents |
|------|----------|
| `references/pbr-shaders.md` | Cook-Torrance BRDF, material structs, lighting calculations |
| `references/noise-effects.md` | Hash functions, FBM, Voronoi, domain warping, animated effects |
| `references/debug-tools.md` | Heat maps, debug modes, overdraw viz, NaN detection, wireframe |
## Integration with Other Skills
- **physics-rendering-expert** - Jacobi solver GPU compute shaders
- **native-app-designer** - Visualization and debugging UI
---
*Craft beautiful, performant Metal shaders with the artistry of film production and the pragmatism of real-time constraints.*
© curiositech · MIT · curiositech/some_claude_skills
