WebGPU-Claude-Skill-Package

Use when building a WebGPU application end to end, setting up the full adapter to device to pipeline to resource chain, or deciding which WebGPU skill applies to the current step. Prevents setup-order mistakes, wrong buffer usage flags, and bind-group layout inconsistency. Covers the full WebGPU setup sequence, the decision routing to the 33 detailed WebGPU skills, and end-to-end render and compute scaffolds. Keywords: WebGPU setup, full pipeline, end to end, getting started, scaffold a WebGPU app, which WebGPU skill, orchestrate WebGPU, render pipeline setup, compute pipeline setup, how do I build a WebGPU app.

Use when reviewing or validating generated WebGPU or WGSL code before trusting it, or auditing a WebGPU codebase for correctness. Prevents shipping hallucinated APIs, alignment errors, missing device-loss handling, and unlabeled descriptors. Covers a category-by-category WebGPU review checklist, the consolidated anti-pattern catalog, and routing each issue to the skill that fixes it. Keywords: WebGPU code review, validate WebGPU code, audit, quality check, review WGSL, is this WebGPU code correct, hallucinated API, alignment error, checklist, what is wrong with my WebGPU code.

Use when debugging WebGPU: diagnosing validation messages, surfacing WGSL compile errors, or capturing a GPU frame. Prevents the undebuggable-from-a-generic-message problem caused by unlabeled descriptors. Covers object labels, error scopes for isolation, getCompilationInfo and GPUCompilationMessage, debug groups and markers, and browser GPU tooling. Keywords: WebGPU debugging, label, getCompilationInfo, GPUCompilationMessage, shader compile error, debug group, insertDebugMarker, RenderDoc, chrome gpu, how do I debug WebGPU, where is my shader error.

Use when handling WebGPU device loss, the device.lost promise, or recovering after a GPU process crash. Prevents the silent-retry-loop anti-pattern and recovering after an intentional device.destroy. Covers the device.lost promise, GPUDeviceLostInfo reason values, and the explicit recovery pattern that recreates every GPU resource. Keywords: device lost, device.lost, GPUDeviceLostInfo, device loss recovery, device.destroy, GPU process crashed, WebGPU stopped working, reason destroyed, reason unknown, how do I recover from device loss.

Use when a WebGPU call fails validation, when capturing errors with error scopes, or when handling the uncapturederror event. Prevents the mistake of treating uncapturederror like a synchronous getError. Covers GPUValidationError, GPUOutOfMemoryError, GPUInternalError, pushErrorScope and popErrorScope, the uncapturederror event, and the contagious-error model. Keywords: validation error, GPUValidationError, GPUOutOfMemoryError, pushErrorScope, popErrorScope, uncapturederror, GPUError, error scope, why did my WebGPU call fail, how do I debug a validation error.

Use when building WebGPU compute workloads: image processing, particle systems, physics simulation, or reduction and prefix-sum. Prevents data races and stale-read bugs in multi-pass compute pipelines. Covers image processing, particle systems, physics simulation, reduction and scan patterns, and workgroup-shared-memory tiling. Keywords: compute use case, image processing, blur, particle system, physics simulation, reduction, prefix sum, scan, workgroup shared memory, storage texture, ping-pong, how do I do GPU compute, GPGPU.

Use when building WebGPU render workloads: PBR materials, full-screen passes, post-processing, or screen-space effects. Prevents the unnecessary-vertex-buffer mistake for full-screen passes and WebGL clip-space assumptions. Covers PBR material setup, the full-screen oversized-triangle trick, post-processing, and screen-space effects like SSAO and SSR. Keywords: render use case, PBR, physically based rendering, full-screen quad, full-screen triangle, post-processing, screen-space effects, SSAO, SSR, how do I render PBR materials, full screen pass.

Use when porting a WebGL or WebGL2 application to WebGPU, or mapping a WebGL concept to its WebGPU equivalent. Prevents broken ports from clip-space differences and the missing automatic mipmap generation. Covers the WebGL to WebGPU concept mapping, clip-space Z range, command encoders versus immediate mode, bind groups versus uniforms, and manual mipmap generation. Keywords: WebGL to WebGPU, migration, port, WebGL2, clip space, GLSL to WGSL, framebuffer to render pass, generateMipmap, manual mipmap, immediate mode, how do I port WebGL to WebGPU.

Use when structuring a WebGPU frame loop, mapping buffers asynchronously, or loading pipelines without blocking. Prevents CPU-GPU stalls that collapse frame pipelining and the buffer-already-mapped error. Covers the mapAsync map-state lifecycle, onSubmittedWorkDone, createRenderPipelineAsync, the requestAnimationFrame frame loop, and avoiding GPU stalls. Keywords: async, mapAsync, mapState, onSubmittedWorkDone, createRenderPipelineAsync, requestAnimationFrame, frame loop, GPU stall, low frame rate, buffer is already mapped, how do I structure a WebGPU render loop.

Use when uploading data to a WebGPU buffer or texture, or reading GPU results back to the CPU. Prevents the copy-failed validation error from unpadded bytesPerRow and stale readback data. Covers the upload decision tree (writeBuffer, mappedAtCreation, staging ring) and the GPU to CPU readback workflow with the 256-byte bytesPerRow padding. Keywords: buffer upload, writeBuffer, mappedAtCreation, staging buffer, readback, copyBufferToBuffer, copyTextureToBuffer, bytesPerRow, GPU to CPU, read pixels, download texture, how do I read data back from the GPU.

Use when optimizing WebGPU performance: reducing command-submission cost, caching pipelines, using render bundles, or profiling on the GPU. Prevents the per-frame rebuild anti-patterns that negate caching and bundle replay. Covers workgroup-size tuning, pipeline and bind-group caching, render bundles, command-buffer reuse, state-change minimization, and timestamp-query profiling. Keywords: performance, optimization, render bundle, GPURenderBundleEncoder, executeBundles, pipeline caching, workgroup size, timestamp-query, profiling, slow frame rate, draw call overhead, how do I make WebGPU faster.

Use when drawing many instances, issuing indirect draws or dispatches, or building GPU-driven rendering. Prevents corrupt geometry from wrong indirect buffer strides and the silently ignored firstInstance. Covers instanced draws, drawIndirect and drawIndexedIndirect with exact buffer layouts, dispatchWorkgroupsIndirect, GPU-driven rendering, and multiDrawIndirect. Keywords: instancing, instanced draw, instanceCount, drawIndirect, drawIndexedIndirect, dispatchWorkgroupsIndirect, indirect buffer, GPU-driven rendering, multiDrawIndirect, firstInstance, instance_index, how do I draw many objects.

Use when building multi-pass WebGPU rendering: post-processing chains, deferred shading, shadow mapping, or ping-pong buffers. Prevents the same-pass read-write hazard from sampling a texture still bound as an attachment. Covers multi-pass rendering, post-processing chains, deferred shading G-buffers, shadow mapping, ping-pong buffers, and intermediate render textures. Keywords: multi-pass, post-processing, deferred shading, G-buffer, shadow mapping, ping-pong, intermediate texture, render to texture then sample, bloom, screen effect, how do I do post processing in WebGPU.

Use when setting up WebGPU render pass attachments: the canvas target, multiple render targets, a depth-stencil buffer, or MSAA. Prevents pipeline / attachment format mismatches and the wrong-sampleCount MSAA bug. Covers color attachments, multiple render targets, depth-stencil attachment and depth formats, MSAA with sampleCount and resolveTarget, loadOp storeOp clearValue. Keywords: render target, colorAttachments, depthStencilAttachment, MRT, multiple render targets, MSAA, multisample, resolveTarget, loadOp, storeOp, clearValue, depth buffer, how do I render to a texture, antialiasing.

Use when writing a WGSL compute shader: workgroup size, invocation ids, shared workgroup memory, atomics, and barriers. Prevents the missing-workgroup-size error and workgroup-memory data races from missing barriers. Covers @compute and @workgroup_size, workgroup_id local global invocation ids, var workgroup shared memory, atomics, workgroupBarrier and storageBarrier, subgroups. Keywords: WGSL compute shader, @compute, @workgroup_size, global_invocation_id, local_invocation_id, workgroup_id, var<workgroup>, atomic, workgroupBarrier, storageBarrier, subgroup, shared memory, data race, how do I write a compute shader.

Use when writing a WGSL fragment shader: color outputs, multiple render targets, depth output, sample-rate shading, or discard. Prevents target / output mismatches and the lost-early-Z bug from writing frag_depth. Covers the @fragment entry point, @builtin position front_facing frag_depth sample_index sample_mask, MRT @location outputs, sample-rate shading, and discard. Keywords: WGSL fragment shader, @fragment, @builtin(frag_depth), @builtin(front_facing), MRT, multiple render targets, discard, sample_index, sample mask, how do I write a fragment shader, pixel shader.

Use when writing a WGSL vertex shader: declaring vertex attributes, the clip-space position output, and inter-stage varyings. Prevents pipeline failures from attribute / location mismatches and the non-flat-integer-varying error. Covers the @vertex entry point, @location vertex attributes, @builtin vertex_index instance_index position, inter-stage varyings, @interpolate, and @invariant. Keywords: WGSL vertex shader, @vertex, @location, @builtin(position), vertex_index, instance_index, varyings, interpolate, clip space, vertex attributes, how do I write a vertex shader, inter-stage variable.

Use when calling WGSL builtin functions (math, geometric, integer, pack) or declaring builtin input and output values in shaders. Prevents shader-creation errors from stage-restricted builtins and wrong builtin value types. Covers WGSL builtin functions by category and the builtin values per shader stage with their direction and type. Keywords: WGSL builtin, dot, cross, normalize, mix, clamp, pow, atomicAdd, dpdx, pack4x8unorm, builtin position, global_invocation_id, vertex_index, builtin value, what WGSL functions are available.

Use when declaring WGSL texture and sampler variables or sampling, loading, and storing texels in a shader. Prevents shader-creation errors from wrong handle types and stage-illegal texture calls. Covers WGSL texture handle types, sampler and sampler_comparison, the textureSample family, textureLoad, textureStore, textureGather, and per-stage legality. Keywords: WGSL texture, texture_2d, texture_depth_2d, texture_storage_2d, texture_external, sampler, sampler_comparison, textureSample, textureSampleLevel, textureLoad, textureStore, how do I sample a texture in WGSL, texture in compute shader.

Use when a WGSL shader hits a uniformity or derivative_uniformity diagnostic, or when enabling optional WGSL features with enable or requires directives. Prevents shader-creation errors from calling textureSample, derivatives, or barriers in non-uniform control flow. Covers uniform control flow, the uniformity analysis, derivative_uniformity diagnostics, the diagnostic directive, and enable / requires feature gating. Keywords: WGSL uniformity, uniform control flow, derivative_uniformity, diagnostic, enable f16, requires, textureSample uniformity error, workgroupBarrier divergent, must be called from uniform control flow.

Use when configuring a WebGPU canvas, presenting rendered frames, or handling canvas resize. Prevents the black-canvas bug from caching getCurrentTexture and the blurry-upscale bug from CSS-only sizing. Covers getContext webgpu, GPUCanvasConfiguration, configure, getCurrentTexture, alphaMode, getPreferredCanvasFormat, and the ResizeObserver resize pattern. Keywords: getContext webgpu, GPUCanvasContext, configure, getCurrentTexture, getPreferredCanvasFormat, alphaMode, canvas resize, black canvas, blurry canvas, nothing renders, how do I show WebGPU output on a canvas.

Use when laying out WGSL structs for uniform or storage buffers, matching a JS typed array to a shader struct, or choosing an address space. Prevents the single most common WGSL bug: uniform struct misalignment from the vec3 16-byte rule producing garbage shader reads. Covers the six WGSL address spaces, pointers, AlignOf and SizeOf rules, the vec3 16-byte trap, the std140-like uniform array stride, align and size attributes. Keywords: WGSL memory layout, address space, uniform, storage, workgroup, vec3 alignment, std140, align, size, struct padding, ptr, arrayLength, shader reads garbage, uniform buffer offset wrong, how do I lay out a uniform struct.

Use when writing WGSL shader code: declaring types, variables, operators, control flow, and functions. Prevents shader-creation errors from wrong type aliases, recursion, and missing switch defaults. Covers WGSL scalar / vector / matrix / array / struct types, var let const override declarations, operators, swizzling, control flow, and functions. Keywords: WGSL, WGSL syntax, vec3f, mat4x4f, var let const override, alias, switch default, swizzle, WGSL function, recursion not allowed, shader compile error, how do I write a WGSL shader.

Use when creating WebGPU bind group layouts and bind groups, wiring uniforms, storage buffers, textures, and samplers into shaders, or using dynamic offsets. Prevents validation failures from layout / shader mismatches and the unaligned-dynamic-offset bug. Covers GPUBindGroupLayout, GPUBindGroup, the five entry layout types, shader-stage visibility, dynamic offsets, and getBindGroupLayout from auto layout. Keywords: createBindGroupLayout, createBindGroup, GPUBindGroupLayoutEntry, GPUShaderStage, dynamic offset, uniform binding, storage buffer binding, sampler binding, group and binding, bind group does not match, getBindGroupLayout.

Use when creating a WebGPU compute pipeline, encoding a compute pass, or dispatching workgroups directly or indirectly. Prevents wrong workgroup-count math and dispatch-versus-workgroup-size confusion. Covers GPUComputePipelineDescriptor, the compute pass encoder, dispatchWorkgroups, dispatchWorkgroupsIndirect, and workgroup-count computation. Keywords: createComputePipeline, GPUComputePipelineDescriptor, dispatchWorkgroups, dispatchWorkgroupsIndirect, compute pass, workgroup count, GPU compute, how do I run a compute shader, workgroup size.

Use when creating a WebGPU render pipeline, configuring vertex buffers, fragment targets, blending, primitive topology, or depth-stencil state. Prevents pipeline-creation validation failures from mismatched vertex layouts, target formats, and depth state. Covers GPURenderPipelineDescriptor, vertex state and GPUVertexBufferLayout, fragment state and targets, primitive state, depth-stencil state, multisample state. Keywords: createRenderPipeline, GPURenderPipelineDescriptor, GPUVertexBufferLayout, vertex attributes, fragment targets, blend state, primitive topology, depth stencil state, cullMode, how do I draw a triangle, pipeline format mismatch.

Use when creating WebGPU buffers, choosing GPUBufferUsage flags, uploading data, or mapping a buffer for CPU access. Prevents validation failures from illegal usage-flag combinations and the buffer-already-mapped error. Covers createBuffer, GPUBufferUsage flags, mappedAtCreation, mapAsync, getMappedRange, unmap, the mapState lifecycle, and queue.writeBuffer. Keywords: createBuffer, GPUBufferUsage, mapAsync, getMappedRange, unmap, mappedAtCreation, writeBuffer, GPUMapMode, buffer is already mapped, MAP_READ, COPY_DST, how do I upload data to the GPU, vertex buffer, uniform buffer.

Use when recording WebGPU commands, beginning render or compute passes, copying buffers and textures, submitting work to the queue, or using query sets. Prevents the encoder-finish-with-open-pass error and the reused-command-buffer mistake. Covers createCommandEncoder, beginRenderPass, beginComputePass, copy methods, finish, queue.submit, onSubmittedWorkDone, GPUQuerySet, and debug groups. Keywords: createCommandEncoder, beginRenderPass, beginComputePass, queue.submit, copyBufferToBuffer, finish, onSubmittedWorkDone, createQuerySet, resolveQuerySet, timestamp query, command buffer, pass end, how do I submit work to the GPU.

Use when creating WebGPU textures, texture views, or samplers, choosing a texture format, or importing a video frame as an external texture. Prevents validation failures from wrong usage flags, sampler / binding-type mismatches, and stale external-texture references. Covers createTexture, GPUTextureFormat, GPUTextureUsage, createView and view dimensions, mip levels, multisample textures, createSampler, and importExternalTexture. Keywords: createTexture, createView, createSampler, GPUTextureFormat, GPUTextureUsage, GPUSampler, importExternalTexture, mip levels, multisample, texture binding, comparison sampler, how do I load a texture, blurry texture, video texture.

Use when writing WebGPU code that must run across Chrome, Safari, and Firefox, or when a feature works in one browser but not another. Prevents apps breaking on Safari or Firefox from Chrome-only assumptions. Covers Chrome / Safari / Firefox WebGPU support differences, feature-detection patterns, version gating, wgslLanguageFeatures, and getPreferredCanvasFormat. Keywords: cross-browser, Chrome, Safari, Firefox, WebGPU support, feature detection, getPreferredCanvasFormat, wgslLanguageFeatures, works in Chrome not Safari, WebGPU not working in Firefox, browser compatibility.

Use when computing buffer sizes, copy offsets, bytesPerRow for texture copies, or dynamic bind-group offsets in WebGPU. Prevents the most common WebGPU validation failures caused by misaligned sizes and offsets. Covers host-side alignment rules: buffer size, writeBuffer, mapAsync and getMappedRange offsets, dynamic buffer offsets, the 256-byte bytesPerRow rule. Keywords: alignment, bytesPerRow, minUniformBufferOffsetAlignment, minStorageBufferOffsetAlignment, dynamic offset, buffer size multiple of 4, validation error, copy failed, bytesPerRow must be multiple of 256, why does my copy fail, offset alignment.

Use when running WebGPU inside a Web Worker or rendering to an OffscreenCanvas off the main thread. Prevents main-thread jank and the mistake of trying to access a DOM canvas from a worker. Covers WorkerNavigator.gpu, OffscreenCanvas, transferControlToOffscreen, worker WebGPU context setup, and unsupported worker contexts. Keywords: Web Worker, OffscreenCanvas, transferControlToOffscreen, WorkerNavigator.gpu, render on worker thread, off main thread, navigator.gpu in worker, how do I run WebGPU in a worker, main thread jank.

Use when initializing WebGPU, setting up navigator.gpu, or reasoning about the adapter / device / queue model and application lifecycle. Prevents the dead-device bug from not null-checking the adapter and from treating device.queue as a method. Covers navigator.gpu, requestAdapter, requestDevice, GPUQueue, the adapter/device ownership model, the 4-phase runtime model, and the secure-context requirement. Keywords: navigator.gpu, requestAdapter, requestDevice, GPUAdapter, GPUDevice, GPUQueue, WebGPU initialization, navigator.gpu is undefined, requestAdapter returns null, WebGPU not available, how do I start with WebGPU, getting started.

Use when negotiating WebGPU device limits and optional features, calling requestDevice with requiredLimits or requiredFeatures, or targeting the compatibility tier. Prevents requestDevice failures from requesting a feature or limit the adapter does not support. Covers GPUSupportedLimits and defaults, the limit negotiation algorithm, the full GPUFeatureName enum with version gates, and featureLevel "compatibility". Keywords: requiredLimits, requiredFeatures, GPUFeatureName, GPUSupportedLimits, adapter.features, maxBufferSize, timestamp-query, shader-f16, featureLevel, compatibility mode, requestDevice failed, feature not supported, how do I check WebGPU support.

Use when reasoning about WebGPU render versus compute pipelines, shader modules, pipeline layouts, or choosing auto layout versus an explicit pipeline layout. Prevents the non-reusable-bind-group bug from auto layout and pipeline-creation jank from synchronous compilation. Covers GPUShaderModule, render and compute pipeline concepts, explicit versus auto pipeline layout, async pipeline creation, and pipeline reuse. Keywords: GPURenderPipeline, GPUComputePipeline, GPUShaderModule, GPUPipelineLayout, createShaderModule, auto layout, createRenderPipelineAsync, getBindGroupLayout, pipeline layout, bind group not reusable, pipeline jank, how do WebGPU pipelines work.