metal-gpu-debug

Automate Metal GPU trace collection, parsing, and analysis on macOS.

1.7k|68|Updated Jun 23, 2025
One-click install
npx skills add https://github.com/trymirai/uzu --skill metal-gpu-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: metal-gpu-debug
Source: https://github.com/trymirai/uzu/tree/main/agents/skills/metal-gpu-debug
Command: npx skills add https://github.com/trymirai/uzu --skill metal-gpu-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Metal GPU debugging and profiling on macOS requires coordinating multiple tools (gpu_trace, xctrace, xcrun metal) to capture, parse, and interpret GPU activity and shader behavior. This skill provides an end-to-end workflow to automate environment validation, trace collection, data extraction, and reporting for Metal workloads on Apple Silicon.

Core Features & Use Cases

  • Automated session lifecycle: doctor/checks, record, export, parse, analyze, and report traces.
  • GPU trace tooling integration: gpu_trace, xctrace, and Metal validation layers for comprehensive debugging.
  • Performance insights: per-kernel timing, hardware counters, and HUD metrics to identify bottlenecks.

Quick Start

Record a Metal System Trace for your app with gpu_trace run, then analyze the trace with gpu_trace analyze and review the generated output.

Frequently Asked Questions about metal-gpu-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug Metal GPU workloads on Apple Silicon?

To debug Metal GPU workloads on Apple Silicon, use this skill to automate environment validation, trace collection, data extraction, and reporting. It coordinates multiple tools to capture GPU activity and analyze shader behavior for comprehensive performance tuning.

Can I profile per-kernel timing and hardware counters with xctrace?

Yes, you can profile per-kernel timing and hardware counters with xctrace. This skill integrates xctrace and gpu_trace to parse trace data, extracting detailed metrics and HUD insights to identify performance bottlenecks in your Metal applications.

Does Metal GPU profiling work with MoltenVK applications?

Metal GPU profiling works with MoltenVK applications. This skill orchestrates trace recording and analysis for both native Metal apps and MoltenVK, capturing GPU intervals and counters to support debugging across different graphics stacks.

What is the best way to automate Metal shader validation during development?

The best way to automate Metal shader validation is by applying Metal validation layers during an automated trace session. This skill manages the session lifecycle from recording to analysis, capturing shader behavior and generating detailed reports.

How do I generate GPU trace analysis reports for Metal apps?

You generate GPU trace analysis reports for Metal apps by recording a system trace with gpu_trace run and analyzing it with gpu_trace analyze. This skill automates the export and parsing of traces to produce per-kernel timings and counters.