axiom-metal-migration-diag

Diagnose and resolve common Apple Metal porting issues with decision trees and code fixes.

Updated Dec 3, 2025
One-click install
npx skills add https://github.com/tuliopc23/flying-dutchman-app --skill axiom-metal-migration-diag
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: axiom-metal-migration-diag
Source: https://github.com/tuliopc23/flying-dutchman-app/tree/main/.claude/skills/axiom-metal-migration-diag
Command: npx skills add https://github.com/tuliopc23/flying-dutchman-app --skill axiom-metal-migration-diag

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides systematic diagnosis and solutions for common issues encountered when porting applications to Apple's Metal graphics API, such as black screens, rendering artifacts, shader errors, and performance regressions.

Core Features & Use Cases

  • Comprehensive Diagnostics: Covers black screens, shader compilation errors, incorrect colors/coordinates, performance issues, and GPU crashes.
  • Decision Trees: Guides users through logical steps to identify the root cause of Metal porting problems.
  • Quick Fixes: Offers concrete code examples and configuration advice for common Metal migration challenges.
  • Use Case: When a game's visuals turn black after migrating from OpenGL to Metal, this Skill helps pinpoint whether the issue is with render pass descriptors, pipeline states, resource binding, or coordinate systems.

Quick Start

Use the axiom-metal-migration-diag skill to diagnose a black screen issue after porting to Metal.

Frequently Asked Questions about axiom-metal-migration-diag

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

FAQPage Schema
Why does my screen turn black after porting from OpenGL to Metal?

A black screen during Metal porting usually stems from incorrect render pass descriptors, missing pipeline states, or improper resource binding. You can diagnose the root cause by following a decision tree that checks Metal API validation and coordinate system differences.

How do I fix incorrect rendering and coordinate system issues in Metal?

Incorrect rendering in Metal is frequently caused by mismatched coordinate systems or improper resource binding. Diagnosing the issue involves checking your pipeline states and verifying that vertex data aligns with Metal's expected coordinate spaces.

What is the best way to debug performance regressions and GPU crashes on iOS and macOS?

Debugging Metal performance regressions and GPU crashes requires checking API validation and resource binding. You can use provided debugging tool guidance to analyze pipeline states and identify the exact point of failure on iOS, macOS, or tvOS.

Can I use this diagnostic approach for tvOS development as well as iOS and macOS?

Yes, the Metal porting diagnostics cover iOS, macOS, and tvOS development. You can systematically diagnose shader errors, pipeline state issues, and performance regressions across all these Apple platforms using the same decision trees.

How do I diagnose Metal API validation errors when porting a graphics application?

Diagnosing Metal API validation errors involves checking your pipeline states and resource binding configurations. You can follow logical decision trees to pinpoint whether the validation failure is causing shader compilation errors or GPU crashes.