Individual skill
using-metal-validation
ALWAYS use when a user wants to enable, configure, or run Metal validation — API validation (MTL_DEBUG_LAYER) for CPU-side API misuse, shader validation (MTL_SHADER_VALIDATION) for GPU-side memory errors, or the load/store-action visual indicators. Trigger when working with Metal validation (MTL_DEBUG_LAYER, MTL_SHADER_VALIDATION, the validation layer, API validation, MTL_DEBUG_LAYER_VALIDATE_LOAD_ACTIONS, MTL_DEBUG_LAYER_VALIDATE_STORE_ACTIONS, per-pipeline validation, MTL4PipelineOptions.shaderValidation, validation perf hit), or when encountering symptoms like shader validation errors not appearing, fuchsia color render artifacts, the red/white checkerboard, or zerofill output. Do NOT trigger for general rendering bug diagnosis where validation isn't the relevant tool.
game-porting-skills/skills/using-metal-validation/SKILL.md
Source commit 4f42344c90be22112f46becc3fb9687f423f2f88
What was checked
- Matches the observed repository HEAD
- Yes
- Scanner rules are current
- Yes
- Repository scan complete
- No
- Skill scan complete
- No
- Observed behavior
- Instructions only
- Last checked
- Nov 5, 2026
These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.
Install this skill
Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.
An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.
Repository context
- Repository stars (not skill ratings)
- 219
- Repository last updated
- Jun 8, 2026
- License
- Apache-2.0
Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.
- design Derived category
Files and excerpt
File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.
Read excerpt
# Using Metal Validation
## Overview
Metal provides two validation modes, both configured via environment variables read at `MTLDevice` creation:
- **API validation** (`MTL_DEBUG_LAYER`) — CPU-side. Cheap; enable broadly during development.
- **Shader validation** (`MTL_SHADER_VALIDATION`) — GPU-side. Potentially significant perf cost; enable selectively or per-pipeline.
Env vars must be set **before** any `MTLDevice` is created. Changes after device creation have no effect.
## Step 1: Read the man page
The man page is the authoritative reference for all env vars, their valid mode values, and pipeline scoping syntax. Read it before configuring anything beyond the quick-start: