给 Claude 写一个 WebGPU Skill

写 Three.js WebGPU 应用时，模型很容易把旧的 WebGL / GLSL 习惯带进来：入口 import 写错、材质属性还用 .map、TSL 链式写法乱成一团。dgreenheck 的 webgpu-claude-skill 就是专门把这套知识打包成 Agent Skill，让 Claude（以及 Cursor）在相关文件上自动对齐当前 API。

仓库大约 1.1k star，内容按 Three.js r183+ 对齐过，覆盖 WebGPURenderer、TSL、节点材质、GPU compute、后处理和设备丢失恢复。

这个 Skill 解决什么问题

TSL（Three.js Shading Language）用 JavaScript 写节点着色器，而不是手搓 GLSL/WGSL 字符串。好处是可组合、可复用，坑在于文档散、版本差异大。这个 Skill 把常用路径收敛成一份可装载的说明书，并附上可跑的示例和模板。

它同时适配两种工作流：

Claude Code：作为 Agent Skill 安装
Cursor：通过 .cursor/rules/ 的 glob 自动挂上，规则文件用 @file 引用同一套 skills/ 文档

安装

Claude Code

把 skills/webgpu-threejs-tsl 拷到全局或项目目录：

bash

# 全局
cp -R skills/webgpu-threejs-tsl ~/.claude/skills/

# 或项目内
cp -R skills/webgpu-threejs-tsl <project>/.claude/skills/

也可以用仓库自带的 /skill install 流程（把用户名换成你的 fork）。

Cursor

把下面两个目录一起拷进项目根目录，路径不要拆开：

text

your-project/
├── .cursor/rules/
└── skills/webgpu-threejs-tsl/

规则按文件名自动触发，例如 *compute* / *particle* 会挂上 compute 文档，*post* / *bloom* 会挂上后处理，*renderer* / *webgpu* 会挂上设备丢失与限制说明。

里面有什么

text

skills/webgpu-threejs-tsl/
├── SKILL.md
├── REFERENCE.md
├── docs/
│   ├── core-concepts.md
│   ├── materials.md
│   ├── compute-shaders.md
│   ├── post-processing.md
│   ├── wgsl-integration.md
│   └── device-loss.md
├── examples/
│   ├── basic-setup.js
│   ├── custom-material.js
│   ├── particle-system.js
│   ├── post-processing.js
│   └── earth-shader.js
└── templates/
    ├── webgpu-project.js
    └── compute-shader.js

文档管「怎么写」，examples / templates 管「直接抄一版能跑的」。

最小可用写法

入口一定要从 three/webgpu 和 three/tsl 进，不要再走旧的 WebGL 路径：

javascript

import * as THREE from 'three/webgpu';
import { color, time, oscSine, normalWorld, cameraPosition, positionWorld, Fn, float } from 'three/tsl';

const renderer = new THREE.WebGPURenderer();
await renderer.init();

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(0x0066ff);
material.emissiveNode = Fn(() => {
  const viewDir = cameraPosition.sub(positionWorld).normalize();
  const fresnel = float(1).sub(normalWorld.dot(viewDir).saturate()).pow(3);
  return color(0x00ffff).mul(fresnel).mul(oscSine(time));
})();

几个容易踩的点：

材质属性改用 colorNode / roughnessNode / positionNode，不要继续写 material.map
TSL 用链式：time.mul(2).sin().mul(0.5).add(0.5)，别混成旧的函数套娃
自定义逻辑用 Fn() 包一层，方便复用

设备丢失：Skill 里专门补的一块

长时间跑 WebGPU（尤其是复杂 compute / 粒子）时，GPU 可能丢失设备。作者后来专门加了 device-loss.md，覆盖：

怎么侦测 device loss
恢复策略和状态重建
用 destroy()、Chrome GPU 崩溃做测试

如果你的 Agent 只会「写个漂亮 shader」，却不会在丢设备后把场景拉回来，这块文档就很有用。

什么时候该开这个 Skill

适合：

新开 Three.js WebGPU 项目
从 GLSL / WebGL 迁到 TSL
做粒子、后处理、自定义材质、混合 WGSL

不太需要：

纯 DOM / 业务前端，不碰 GPU
还在用经典 WebGLRenderer 且短期内不打算换

版本与浏览器

推荐 Three.js r171+（仓库说明按 r183+ API 同步过）
浏览器：Chrome / Edge 113+；Firefox、Safari 的 WebGPU 支持仍要看各自预览开关
r178+ 注意：PI2 改用 TWO_PI，transformedNormalView/World 改名为 normalView/World

字节笔记本