axiom-metal-migration-diag

Diagnose Metal porting issues in iOS and macOS apps.

Updated Dec 23, 2025

Search Tags:#validation #gpu #metal #diagnostic #shader #graphics-porting

Ready to run

npx skills add https://github.com/pradeepmouli/swift-template --skill axiom-metal-migration-diag-pradeepmouli

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: axiom-metal-migration-diag
Source: https://github.com/pradeepmouli/swift-template/tree/main/.agents/skills/axiom-metal-migration-diag
Command: npx skills add https://github.com/pradeepmouli/swift-template --skill axiom-metal-migration-diag-pradeepmouli

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Metal porting challenges cause black screens, shader errors, color/coordinate mismatches, performance regressions, and GPU crashes during migration to Metal on Apple platforms. This diagnostic provides a structured approach to identify, reproduce, and fix those issues.

Core Features & Use Cases

Systematic decision trees for common symptoms: Black Screen, Shader compilation errors, Wrong colors, Performance regressions, and Crashes.
Guided validation and debugging workflows: Enable Metal validation, GPU frame capture, shader debugging, and interpretation of validation messages to surface root causes quickly.
Diagnostic checklist and resources: Step-by-step checks and references (WWDC talks and official docs) to reproduce fixes across iOS and macOS platforms.

Quick Start

Enable Metal validation in Xcode, then follow the diagnostic steps to identify and fix porting issues.

Frequently Asked Questions about axiom-metal-migration-diag

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

FAQPage Schema

Why is my Metal porting showing a black screen after migrating my graphics shaders?▼

A black screen during Metal porting typically results from incorrect resource binding or coordinate system mismatches. This diagnostic checklist helps identify the root cause by systematically verifying GPU frame capture data, shader compilation outputs, and resource binding checks to resolve the rendering failure.

How do I debug Metal shader compilation errors in iOS and macOS apps?▼

To debug Metal shader compilation errors, enable Metal validation in Xcode to surface detailed validation messages. This diagnostic workflow interprets those messages to quickly identify shader code issues, coordinate discrepancies, and incorrect color outputs across iOS and macOS platforms.

What is the best way to diagnose GPU crashes and performance regressions during Metal migration?▼

The best way to diagnose GPU crashes and performance regressions during Metal migration is using structured decision trees. This diagnostic approach guides developers through enabling GPU frame capture and interpreting validation messages to isolate and fix the underlying GPU faults.

Does this Metal diagnostic workflow require enabling GPU frame capture in Xcode?▼

Yes, enabling Metal validation and GPU frame capture in Xcode is the prerequisite quick start step. This diagnostic builds upon that enabled validation state to interpret shader debugging outputs and execute its comprehensive diagnostic checklist effectively.

How do I fix coordinate system discrepancies when porting to Metal on Apple platforms?▼

Fixing coordinate system discrepancies when porting to Metal requires checking shader outputs and resource bindings against the target platform's expectations. The diagnostic checklist provides step-by-step verification workflows to identify and correct these color and coordinate mismatches.