Skip to content
Skills Library
Programming · Analysis

webgpu-capture-analysis

/webgpu-capture-analysis

Interpret WebGPU Inspector frame captures — the GPU object graph, the command list, render/compute passes, buffers, textures, shaders, validation errors, and common performance problems. Use when analyzing captures produced by the webgpu-inspector plugin's MCP tools or by saveCaptureData() / DevTools "Save Capture" files (.wgpuc binary, or legacy .json).

Licence
MIT
Last repository change
21.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Interpret WebGPU Inspector frame captures — the GPU object graph, the command list, render/compute passes, buffers, textures, shaders, validation errors, and common performance problems. Use when analyzing captures produced by the webgpu-inspector plugin's MCP tools or by saveCaptureData() / DevTools "Save Capture" files (.wgpuc binary, or legacy .json).

Triggers from the description

s MCP tools or by saveCaptureData() / DevTools
Original author description

Interpret WebGPU Inspector frame captures — the GPU object graph, the command list, render/compute passes, buffers, textures, shaders, validation errors, and common performance problems. Use when analyzing captures produced by the webgpu-inspector plugin's MCP tools or by saveCaptureData() / DevTools "Save Capture" files (.wgpuc binary, or legacy .json).

How it works

  1. Capture files
  2. Capture shape
  3. Workflow
  4. Performance analysis
  5. What to look for
  6. Reporting
Original SKILL.md headings · 163 lines, 1,261 words
SKILL.md preview
---
name: webgpu-capture-analysis
description: >-
  Interpret WebGPU Inspector frame captures — the GPU object graph, the command
  list, render/compute passes, buffers, textures, shaders, validation errors,
  and common performance problems. Use when analyzing captures produced by the
  webgpu-inspector plugin's MCP tools or by saveCaptureData() / DevTools "Save
  Capture" files (.wgpuc binary, or legacy .json).
---

# WebGPU capture analysis

A WebGPU Inspector capture is a record of one or more rendered frames: the
full GPU object graph plus the ordered list of WebGPU API calls. This skill
explains how to read one and what to flag.

## Capture files

Saved captures are `.wgpuc` binary files: an ASCII header line
(`WGPUCAP <version> <jsonByteLength>\n`), then `<jsonByteLength>` bytes of
metadata JSON (the object described under "Capture shape" below, so the front
of the file is readable text), then raw buffer/texture payload bytes located
by the metadata's `payloadTable`. Don't parse one by hand — pass the path to
`load_capture_file` and use the MCP tools. Legacy captures (single-object
`.json`, or NDJSON with base64 payload lines) load the same way.

## Capture shape

- `objects` — map of numeric id to a record: `{ id, type, label, descriptor,
  stacktrace, ... }`. Types: `Adapter`, `Device`, `Buffer`, `Texture`,
  `TextureView`, `Sampler`, `BindGroup`, `BindGroupLayout`, `PipelineLayout`,
  `RenderPipeline`, `ComputePipeline`, `ShaderModule`, `RenderBundle`.
- `commands` — ordered array of `{ index, method, object, args, result, ... }`.
  `object` is the GPU object the method was called on; `args` are its
  arguments. References to GPU objects appear as `{ "__id": N, "__class": ...,
  "__label": ... }`.
- `validationErrors` — WebGPU validation errors raised during the capture.
- Large buffer/texture payloads live out-of-band (referenced by
  `__payloadId`); the MCP tools strip them, so you see `__base64Omitted`
  markers and byte lengths instead of bytes.

## Workflow

Always start with `get_capture_summary` — it carries object/command counts,
derived stats, and a heuristic `issues` list. Then drill in:

- `get_commands` with a `method` filter, a `passLabel` regex, or an
  `offset`/`limit` window — never fetch the whole list at once for a large capture.
- `get_object` for a pipeline, bind group, or texture descriptor.
- `get_shader` for a ShaderModule's WGSL.
- `get_validation_errors` for correctness problems.

To debug a specific draw (e.g. "this draw read a vertex attribute as 0"):

- `get_draw_state(commandIndex)` resolves the bound pipeline (+ vertex layout),
  bind groups, vertex/index buffers, and draw params for a draw command. Each
  vertex buffer reports a `bufferDataCommandIndex`.
- `decode_vertex_buffer(commandIndex)` — pass a vertex buffer's
  `bufferDataCommandIndex` to decode its first N vertices into per-attribute
  numbers (the layout is taken from the pipeline automatically).
- `diff_draws(cmdA, cmdB)` compares a working vs. a broken draw's resolved state.
- `get_pixel_history(textureId, x, y)` lists every fragment that touched a pixel
  and why it was kept or dropped (depth-failed, stencil-failed, discarded,
  scissored, ...). Use it for "why is this pixel black / wrong / missing".
- `debug_shader(commandIndex, ...)` runs one invocation on the CPU with the
  captured resources: `vertexIndex` for a vertex, `x`/`y` for a fragment,
  `invocation` for compute. Pass `watch: ["name", ...]` for a line-by-line trace
  of variables. Its `missingData` field says when the capture lacks the bound
  buffers' bytes; recapture with `payloads: "all"` then.
- `get_frame_issues` runs the Frame Issues rules and `get_render_graph` shows
  the pass dependencies (results nothing reads, overwritten before read, reads
  of discarded attachments).

To try a shader fix on the live page, `replace_shader(shaderId, code)` swaps the
module's WGSL (it reports validation errors), then check with `screenshot_page`
or a new capture; `restore_shader` undoes it. Capture ids and live ids match.

For very large frames, capture only what you need: `capture_frames` accepts
`passLabel` / `passType` (capture heavy payloads for matching passes only) and
`maxBufferSize` (per-buffer byte cap; truncated buffers are marked). To inspect a
live buffer without a full capture, use `read_buffer`.

Cite `index` (command) and `id` (object) values in findings so the user can
locate them in the WebGPU Inspector DevTools Capture panel.

## Performance analysis

When the goal is performance — the frame is slow, janky, dropping frames, or the
user asks where the time goes / whether it's CPU- or GPU-bound / about fillrate —
take the GPU-timed path **by default, without being asked to enable it**:

1. Capture with per-pass GPU timing:
   `capture_frames({ profilePasses: true, payloads: "none" })`. `profilePasses`
   injects per-pass GPU timestamp queries so each render/compute pass carries a
   measured `durationMs` (and the frame a total GPU time); `payloads: "none"` keeps
   the capture light — profiling needs the command list and object graph, not the
   buffer/texture bytes. **Treat "analyze the performance of a frame" as implying
   `profilePasses: true`.**
2. Call `analyze_performance` (not just `get_capture_summary`). It returns the frame
   budget and a CPU-/GPU-/vsync-bound verdict, passes ranked by GPU time each
   annotated with render-target size/format/MSAA, blend usage, fragment-shader
   complexity, and a likely bottleneck (fillrate/ROP vs fragment-ALU), plus
   heuristic issues and ranked improvement suggestions.
3. For a live page, `get_frame_stats` samples fps / dropped frames / CPU submit time
   / bound verdict over a short window without a capture — use it to confirm the page
   is actually dropping frames or is CPU-bound before drilling in.
4. `get_bottlenecks` gives each pass a verdict from its GPU time, primitives and
   fragment counts (tiny triangles, overdraw, fragments shaded then rejected,
   heavy targets). `get_overdraw(textureId)` shows where the overdraw is.
5. To find the expensive shader code: `get_shader_flame_graph` ranks the frame's
   cost by pass, pipeline, stage and statement (`measureDrawTimes: true` measures
   each draw), and `measure_shader_cost(commandIndex)` measures each statement of
   one draw's shader on the GPU.
6. After a change, recapture and `compare_captures(captureA, captureB)` to show
   what moved.

The GPU-replay tools (`get_bottlenecks`' counts, `get_overdraw`,
`measure_shader_cost`, `measureDrawTimes`) need a browser from `launch_browser`
or `attach_browser`; they replay the capture in a tab of their own.

Notes:
- GPU timing needs the adapter's `timestamp-query` feature; the inspector enables it
  automatically when available and it is a no-op otherwise. Without it,
  `analyze_performance` still ranks passes by fill workload and says GPU time is
  unavailable — re-run once the feature is present for real timings.
- The fillrate-vs-fragment-ALU verdict is a static heuristic (render-target bytes ×
  MSAA × area × blend, plus a WGSL fragment-complexity scan). To *confirm* fillrate,
  reduce the render-target resolution and re-measure: GPU time scaling ~linearly with
  pixel count ⇒ per-pixel (fillrate/fragment) bound; flat ⇒ vertex/geometry/CPU bound.

## What to look for

**Correctness**
- Any `validationErrors` — always report these first; they are real bugs.
- A canvas texture used after its frame expired, or destroyed objects still
  referenced (the inspector reports these as validation errors).

**Per-frame cost / hitching**
- `createRenderPipeline` / `createComputePipeline` inside the captured frame —
  pipeline creation is expensive; move it to load time.
- `createShaderModule` inside the frame — same idea.
- Large or numerous `writeBuffer` / `writeTexture` calls every frame — consider
  persistent buffers, mapped writes, or uploading less.

**CPU submission overhead**
- High `setPipeline` / `setBindGroup` / `setVertexBuffer` counts relative to
  draw calls — sort draws by pipeline and bind group to cut state changes.
- Redundant consecutive `setPipeline` / `setBindGroup` (the summary flags
  these) — the bind is a no-op and can be skipped.
- Many small draw calls with the same pipeline — candidates for instancing,
  batching, or render bundles.

**Pass structure**
- Excess `beginRenderPass` calls — each pass has fixed cost; merge where the
  attachments allow.
- `loadOp: "load"` where `"clear"` would do (forces an attachment read), or
  `storeOp: "store"` on attachments whose result is never used.
- Depth/stencil attachment configuration vs. what the draws need.

**Shaders** (via `get_shader`)
- Work in the fragment stage that could move to the vertex stage.
- Dynamically uniform branching, heavy loops, or texture sampling in loops.
- Bind group layout mismatches across entry points.

## Reporting

Give a prioritized list. For each finding: severity (error > warning > info),
a one-line description, why it matters for this capture, and a concrete fix.
Reference command indices and object ids. Distinguish confirmed bugs
(validation errors) from heuristics (a flagged pattern that may be intentional)
— say which is which rather than overstating.

Versions

The database has no other skills named webgpu-capture-analysis.

Database snapshot: 13.11.2026 · package version 09fbca67af57 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90renderer
    Architecture rules for GPU rendering with TypeGPU/WebGPU — games, data visualisation, canvases, any app that draws with the GPU. Use when adding or changing passes, shaders, buffers, textures, pipelines, frame orchestration, GPU resource lifetimes, or checks that judge rendered output.
  • 100guidance-webgpu-performance
    Diagnose and improve browser WebGPU rendering performance, including frame pacing, draw and state-submission overhead, buffer uploads, shaders, and JavaScript work on the render critical path. Use for slow or stuttering GPU-backed interfaces, rendering regressions, CPU/GPU…
  • 86renderer
    Architecture rules for GPU rendering with TypeGPU/WebGPU. Use when adding or changing render passes, shaders, frame orchestration, GPU resources, culling, terrain, shadows, or visual performance work.
  • 95webgpu-webgl-rendering
    Use this skill when the user says 'WebGPU', 'WGSL', 'WebGL2', 'GLSL shader', 'GPU buffer', 'bind group', 'render pipeline', 'compute shader in the browser', 'GPU memory in the browser', 'draw call overhead'. It designs low-level browser GPU rendering and compute: WebGPU…
  • 100threejs-impl-webgpu
    Use when using the Three.js WebGPU renderer, node-based materials, TSL (Three Shading Language), or compute shaders. Prevents the common mistake of not checking browser support, missing async init, or using GLSL with WebGPU. Covers WebGPURenderer, node materials, TSL, compute…
  • 95webgpu-compute-shaders
    Use this skill when the user says 'WebGPU', 'compute shader', 'WGSL', 'workgroup', 'GPGPU in browser', 'storage buffer'. Explains WebGPU compute pipelines, WGSL compute shaders, and workgroup/shared-memory design. Do NOT use for: WebGL rendering, or raytracing geometry math (use…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.