How do I install the Using Gpucapture skill?

Run npx skillmds@latest add apple/using-gpucapture in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Using Gpucapture safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Using Gpucapture?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Using Gpucapture free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Using Gpucapture?

apple (@apple) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Using Gpucapture by apple — Agent Skill

Name: Using Gpucapture
Author: apple

Using Gpucapture

ALWAYS use when a user wants to capture a GPU trace (.gputrace) of a Metal application. Trigger when the user wants to capture a GPU trace, get a gputrace, record a Metal frame, capture a frame, capture GPU workload, use gpucapture, capture from the command line, do a Metal frame capture, ask how to capture a Metal trace, capture a running process, or otherwise create a .gputrace file from a Metal app. Do NOT trigger when the user already has a GPU trace and wants to analyze or diagnose it — use using-gpudebug for that.

apple 7d3e008 2.7 KB Updated Sep 17, 2026

File contents

Using gpucapture — Metal GPU Trace Capture

Overview

gpucapture is a CLI tool for capturing Metal GPU traces from running processes or launched executables. It requires no source code changes — attach to a process by PID, choose what to capture (frames, command buffers, custom scopes), and produce a .gputrace file for analysis.

Step 1: Check availability

which gpucapture

gpucapture ships with macOS 27 and later. If not found, the user is on an older macOS version — suggest alternatives based on their situation:

Can modify source code → Programmatic capture via MTLCaptureManager: Capturing a Metal workload programmatically
Has Xcode available → Xcode's built-in GPU Frame Capture: Capturing a Metal workload in Xcode

If the user explicitly asks for programmatic capture or Xcode capture, honor their request — point them to the relevant Apple docs URL above and answer from your own knowledge. Do not override their choice with gpucapture.

If gpucapture is available and the user has not specified a method, proceed with the steps below.

Step 2: Read the man page

The man page is the authoritative reference for all subcommands, flags, boundary types, and environment variables. Read it before using gpucapture:

man gpucapture | col -b

Step 3: Key requirements

The man page documents all subcommands (list, boundary, start, stop), flags, and boundary types. Two things to keep in mind that are easy to miss:

The target process must be launched with MTL_CAPTURE_ENABLED=1. There is no way to enable capture on an already-running process that was launched without it. If the user says the app is "already running," they likely need to relaunch it.
For apps that exit quickly, MTLCAPTURE_WAIT_FOR_SIGNAL=1 pauses the process at MTLDevice creation until gpucapture start attaches. Both env vars should be set at launch.

After capturing, verify the .gputrace file was created and report the file path and size to the user.

---name: using-gpucapturedescription: ALWAYS use when a user wants to capture a GPU trace (.gputrace) of a Metal application. Trigger when the user wants to capture a GPU trace, get a gputrace, record a Metal frame, capture a frame, capture GPU workload, use gpucapture, capture from the command line, do a Metal frame capture, ask how to capture a Metal trace, capture a running process, or otherwise create a .gputrace file from a Metal app. Do NOT trigger when the user already has a GPU trace and wants to analyze or diagnose it — use using-gpudebug for that.---# Using gpucapture — Metal GPU Trace Capture## Overview`gpucapture` is a CLI tool for capturing Metal GPU traces from running processes or launched executables. It requires no source code changes — attach to a process by PID, choose what to capture (frames, command buffers, custom scopes), and produce a `.gputrace` file for analysis.## Step 1: Check availability```shwhich gpucapture````gpucapture` ships with macOS 27 and later. If not found, the user is on an older macOS version — suggest alternatives based on their situation:- **Can modify source code →** Programmatic capture via `MTLCaptureManager`: [Capturing a Metal workload programmatically](https://developer.apple.com/documentation/xcode/capturing-a-metal-workload-programmatically)- **Has Xcode available →** Xcode's built-in GPU Frame Capture: [Capturing a Metal workload in Xcode](https://developer.apple.com/documentation/xcode/capturing-a-metal-workload-in-xcode)If the user explicitly asks for programmatic capture or Xcode capture, honor their request — point them to the relevant Apple docs URL above and answer from your own knowledge. Do not override their choice with `gpucapture`.If `gpucapture` is available and the user has not specified a method, proceed with the steps below.## Step 2: Read the man pageThe man page is the authoritative reference for all subcommands, flags, boundary types, and environment variables. Read it before using gpucapture:```shman gpucapture | col -b```## Step 3: Key requirementsThe man page documents all subcommands (`list`, `boundary`, `start`, `stop`), flags, and boundary types. Two things to keep in mind that are easy to miss:- **The target process must be launched with `MTL_CAPTURE_ENABLED=1`.** There is no way to enable capture on an already-running process that was launched without it. If the user says the app is "already running," they likely need to relaunch it.- **For apps that exit quickly**, `MTLCAPTURE_WAIT_FOR_SIGNAL=1` pauses the process at `MTLDevice` creation until `gpucapture start` attaches. Both env vars should be set at launch.After capturing, verify the `.gputrace` file was created and report the file path and size to the user.

Frequently asked questions