Design & Motion · dgreenheck/webgpu-claude-skill
webgpu-three-js
Comprehensive guide for developing WebGPU-enabled Three.js applications using TSL (Three.js Shading Language). Covers WebGPU renderer setup, TSL syntax and node materials, compute shaders, post-processing effects, and WGSL integration. Use this skill when working with Three.js WebGPU, TSL shaders, node materials, or GPU compute in Three.js.
L1 Basic · Source registration onlyV1 Commit-PinnedDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
SKILL.md itself is only 93 lines / 3.2KB and functions as a routing table: its body uses 'Skill Contents' to itemize 7 docs, 5 examples, 2 templates, and 1 cheatsheet. The agent progressively discloses and loads the corresponding files based on the active task, rather than flooding the context window with 50KB+ of documentation all at once.
skills/webgpu-threejs-tsl/SKILL.md
- `docs/compute-shaders.md` - GPU compute with instanced arrays
What is happening here: SKILL.md serves solely as an index, delegating 'what to load and when' to the host model. Size comparison: SKILL.md is 3.2KB, whereas the 7 documents in docs/ total 56.6KB and REFERENCE.md is 9.1KB.
On the Cursor side, the same disclosure strategy is formulated as explicit prompts: the .mdc body keeps only a 3–5 line summary and uses @file references pointing to the original documentation under skills/ (the 5 .mdc files total just 5.9KB, yet include 10 @ references).
.cursor/rules/webgpu-threejs-tsl.mdc
The source-of-truth documentation lives under `skills/webgpu-threejs-tsl/`. Reference these files directly when deeper guidance is needed:
The README refers to these .mdc files as thin shims; the @skills/... reference lines can be verified individually via grep (webgpu-threejs-tsl.mdc has 4, compute-shaders.mdc has 3, post-processing.mdc has 2, device-loss-and-limits.mdc has 2, and wgsl-integration.mdc has 1).
The true anchor for 'writing correct code' is a recurring semantic pitfall in TSL emphasized throughout the docs: TSL can only intercept node property assignments, not JS variable reassignments. Writing value = value.add(1.0) inside If() fails silently (returning the old node without throwing errors).
skills/webgpu-threejs-tsl/docs/compute-shaders.md
**TSL can intercept property assignments on nodes, but NOT JavaScript variable reassignment.**
Why this is critical: This is the most typical silent bug in TSL (compilation succeeds, but results are incorrect). The skill repeats this identical warning in three places—core-concepts.md § '⚠️ CRITICAL: Property Assignment vs Variable Reassignment', the beginning of compute-shaders.md, and the header comments of templates/compute-shader.js—and provides three correct alternatives: select(), .toVar(), and direct element.assign().
It provides not just the rule, but also the failure mechanism to prevent models from repeating the same mistake with different phrasing: the documentation explains that JS variable reassignment creates a new node that TSL cannot observe, and scalars lack .x/.y properties, preventing property assignment workarounds.
skills/webgpu-threejs-tsl/docs/compute-shaders.md
**Why it fails:** `value = value.add(1.0)` creates a new TSL node and reassigns the JavaScript variable to point to it.
Supporting argument from the same section: 'Since `value` is a scalar float (no `.x`/`.y` properties), you can't use property assignment.' Thoroughly explaining the underlying mechanism enables the model to generalize to scenarios not explicitly listed in the docs.
Breaking version changes are codified as documentation entries rather than runtime detection: the skill does not inspect the user project's Three.js version, but instead compiles r17x–r18x breaking changes into comparative reference entries for the model to cross-check autonomously.
skills/webgpu-threejs-tsl/docs/post-processing.md
> **Note:** `PostProcessing` was renamed to `RenderPipeline` in r183. `PostProcessing` still works as a compatibility wrapper but is deprecated.
Similar entries: The r178+ section in REFERENCE.md 'Version Notes' (PI2→TWO_PI, transformedNormalView/World→normalView/World), compute-shaders.md 'computeAsync() is deprecated since r181', the complete rewrite of DOF in r181 and recalibration of blur sigma in r177 in post-processing.md, and the list of new effects in r182+. SKILL.md itself contains no 'check project version first' step.
Templates provide directly deployable, full-file scaffolding rather than pseudo-code: segmented structures (CONFIG/GLOBALS/INITIALIZATION/SCENE/ANIMATION/EVENT), designated insertion points, and internal objects exported at the end for external debugging.
skills/webgpu-threejs-tsl/templates/webgpu-project.js
// Export for external access if needed
webgpu-project.js explicitly states usage in its header: '1. Copy this file to your project 2. Install Three.js: npm install three 3. Replace placeholder content with your scene'. compute-shader.js shares the same structure, additionally featuring placeholders and exports for init/update/interaction passes. Its value lies in letting the model bypass project setup, dependency installation, and rendering loop boilerplate unrelated to shaders.
WGSL escape hatch: When TSL cannot express a concept or existing WGSL needs porting, wgslFn() embeds entire WGSL function bodies into the TSL node graph; the documentation also includes quick references for WGSL types, syntax, and built-in functions so the model can write correct WGSL independently of TSL.
skills/webgpu-threejs-tsl/docs/wgsl-integration.md
TSL allows embedding raw WGSL (WebGPU Shading Language) code when you need direct GPU control.
wgsl-integration.md contains complete source code for long functions such as simplex noise and FBM, serving as directly copyable corpus material; the doc also provides a hybrid paradigm of 'use WGSL for complex math, use TSL for simple logic'.
Incorporates WebGPU-specific runtime failure surfaces (device loss, limits/features) into coding guidance, ensuring generated code is not only runnable, but also resilient against GPU crashes and buffer limits.
skills/webgpu-threejs-tsl/docs/limits-and-features.md
Three.js accepts `requiredLimits` as a renderer constructor option, which gets passed through to `requestDevice()`:
Companion materials: limits-and-features.md lists default limits (maxBufferSize 268435456, i.e., 256 MiB, etc.) and safe practices of 'query adapter before requesting'; device-loss.md covers device.lost detection, three recovery strategies (page reload / GPU resource rebuild only / full state restoration), destroy() and about:gpucrash testing methods, and Chrome crash threshold tables.
2Core Capabilities
01WebGPU renderer + TSL project initialization and render loop scaffolding (calling renderer.init() prior to compute/render)
02Full spectrum of TSL node materials: 12 *NodeMaterial types and property mappings including colorNode, roughnessNode, metalnessNode, clearcoatNode, transmissionNode, iridescenceNode, sheenNode, anisotropyNode, and dispersionNode
03GPU compute shaders: instancedArray/attributeArray storage buffers, Fn().compute(count, [workgroupSize]), compute built-ins, workgroup/storage barriers, and atomic operations
04Post-processing pipeline: built-in effects such as bloom, blur, FXAA, SMAA, DOF, SSR, SSAO, film, and outline, multiple MRT passes, custom Fn() effects, and effect chains
05WGSL integration: embedding custom WGSL functions (including simplex noise and FBM) via wgslFn() and intermixing them with TSL nodes
06Device loss detection, recovery, and testing, including state preservation/restoration and fallback notifications
07Querying and requesting WebGPU limits and optional features (transparent pass-through via requiredLimits, query-before-request patterns, features automatically requested by Three.js)
08Runnable examples and starter templates: 5 examples + 2 templates (minimal project, custom materials, 100k-particle compute, post-processing chain, procedural Earth with atmosphere)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| package | three（npm 包，生成项目需自装） |
| package | three/addons 子路径（OrbitControls、BloomNode 等 addons 模块） |
| network | 文档引用链接（仅 markdown 里的参考资料链接，仓库内无任何抓取/请求代码，不被 skill 调用） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Can be auto-loaded
For Administrators
Register source and version
Evidence & Triggers (File Paths & Excerpts)
- SKILL.md: Pure prompt instructions and rule text without script execution or external impact.
Audit Notes: Green tier, pure static knowledge asset: The repository contains only 24 files via git ls-tree, all of which are .md, .mdc, .json, or read-only .js corpus files. There is no package.json, scripts/ directory, or .sh/.py scripts, meaning scripts_executed is empty. Repository-wide grep reveals no fetch, XMLHttpRequest, curl, wget, importmap, or CDN domains (zero hits for unpkg/jsdelivr), leaving the network surface empty (references to threejs.org, toji.dev, and webgpureport.org in README/REFERENCE.md are purely Markdown hyperlinks with no programmatic requests). There are no process.env, .env, token, cookie, or credential references, meaning the credential surface is empty. The skill itself never writes files (localStorage appears only within docs/device-loss.md as sample code demonstrating how user applications can persist state). The only considerations are knowledge freshness and dual-maintenance drift (Cursor summaries lagging behind docs), which are content quality concerns rather than execution risks.
5Second-Pass Verification
- [ok] pin commit 与工作副本一致 — git rev-parse HEAD 输出 af2319bd01bb7cc881267a9ef42cafdaf5e9029d，与 .git/shallow 首行相同，等于任务 pin commit；结论只对该 commit 有效。
- [ok] skill 目录定位 — skills/webgpu-threejs-tsl/SKILL.md 存在且 frontmatter name: webgpu-threejs-tsl 与 slug 对应；同目录含 REFERENCE.md、docs/×7、examples/×5、templates/×2，路径写入 skill.path。
- [discrepancy] license 声明与仓库实际文件 — README.md 有『## License』段声明 MIT License，.claude-plugin/plugin.json 也写 "license": "MIT"；但 git ls-tree -r 全量清单里没有 LICENSE / LICENSE.md 文件，全仓 grep -il license 只命中 plugin.json、README.md 与 5 个 examples 的注释，与 GitHub API license=null 一致。即：许可为『源码内声明』而非仓内标准许可文件。
- [discrepancy] README 自述的 skill 结构图 vs 实际文件 — README『## Skill Structure』的 docs/ 分支只列 core-concepts / materials / compute-shaders / post-processing / wgsl-integration / device-loss 六篇（以 `└── device-loss.md` 收尾），而 docs/ 实有 7 篇——漏列 limits-and-features.md；SKILL.md 的 Skill Contents 则完整列出七篇。属 README 文档漂移。
- [discrepancy] Cursor 摘要与 docs 的 API 世代是否一致（后处理） — .cursor/rules/post-processing.mdc 仍教 `import { PostProcessing } from 'three/webgpu';` 并说 postProcessing.renderAsync()，而 docs/post-processing.md 开篇即注明 r183 已改名 RenderPipeline、旧名仅为兼容包装，examples/post-processing.js 实际用的是 `new THREE.RenderPipeline(renderer)`。README 自称 shim 会『edits flow through automatically』——该说法对手写摘要句不成立。
- [discrepancy] Cursor 摘要与 docs 的 API 世代是否一致（compute 派发） — .cursor/rules/compute-shaders.mdc 写『dispatched via `renderer.computeAsync()`』与『- `renderer.computeAsync(kernel)` to dispatch』，而 docs/compute-shaders.md『Execution Methods』明确『// Note: computeAsync() is deprecated since r181.』并给出『await renderer.init() at startup, then renderer.compute() synchronously』；templates/compute-shader.js 与 examples/particle-system.js 用的都是 renderer.compute(...)。同一漂移问题的第二例。
- [ok] 外部依赖反查：是否存在 CDN/网络调用 — 全仓 grep -riE 'unpkg|jsdelivr|cdn\.|importmap|import-map' 零命中；templates/examples 的 import 全部是裸包名（three、three/webgpu、three/tsl、three/addons/...），无 URL 形式的模块来源。故 external_deps 只列 npm 包，security.network_calls 为空。
- [ok] 脚本/凭证面反查 — git ls-tree 全清单只有 .md/.mdc/.json/.js；无 package.json（因此无 npm scripts、无依赖安装钩子）、无 scripts/、无 .sh/.py；危险 token 扫描对 child_process/eval/new Function/process.env/.env/token/secret/document.cookie/credentials 均无命中。scripts_executed 与 credential_reads 为空有据。
6Verdict & Scenarios
Best for: Ideal for frontend and graphics developers building WebGPU/TSL applications with Three.js, as well as teams leveraging AI agents for shader authoring: yields the highest value when projects target the Three.js r171–r183 generation, specifically for custom node materials, compute particles, post-processing chains, and hybrid WGSL implementations. Also suited as a Claude Code plugin or Cursor rule mounted directly to projects, allowing agents to automatically apply the correct API generation and pitfall warnings when writing *.js/*.wgsl files. Developers looking to bootstrap projects quickly can copy templates/webgpu-project.js directly.
Not for: Not suitable for projects whose Three.js version deviates significantly from r171–r183 (legacy r15x or major future releases will encounter deprecated APIs requiring manual reconciliation); not suitable when treating Cursor rules as the sole source of truth—summaries in two rules have lagged behind, requiring deep-dive checks into docs under skills/; not suitable for pure WebGPU/WGSL or WebGL/GLSL projects (coverage is limited to three/webgpu + TSL); not suitable for workflows requiring immediate executable artifacts or automated validation (no scripts, builds, or tests; accuracy relies on the model faithfully following documentation); not suitable for compliance processes requiring a standard repository-level LICENSE file.
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload webgpu-three-js.tar.gz
sha256:
Option B · Copy Guide for Agentafb594cdc14fec2b…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit af2319bd01.