# axiom-graphics

A router skill for GPU work: Metal migration, shader conversion, RealityKit, USD/USDZ files and display frame rate.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 1229
- Author: CharlesWiltgen
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/CharlesWiltgen/Axiom/tree/HEAD/axiom-codex/skills/axiom-graphics/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/axiom-graphics

## What it does

axiom-graphics is a router, not a single answer file. It reads the task and points the agent at the right reference: OpenGL and DirectX ports to Metal, GLSL and HLSL to Metal Shading Language conversion tables, MTKView and CAMetalLayer setup, and diagnosis of a black screen or wrong colors after a port.

Other branches cover RealityKit in non-game apps: ECS, RealityView and Model3D in SwiftUI, AR on iOS, materials and physics. There is also USDKit for opening, editing and exporting USD and USDZ, HDR tone mapping and color metadata, and display performance — an app pinned at 60fps on a ProMotion screen, CADisplayLink configuration, variable refresh rate.

When rendering blurs or stretches as a window resizes or moves between screens, the router sends you to the resizable-rendering branch. For game-specific RealityKit patterns the author points to the axiom-games router instead. Everything lives in files such as `skills/metal-migration-ref.md` and `skills/realitykit-diag.md`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add CharlesWiltgen/Axiom --skill axiom-graphics -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/axiom-graphics/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/axiom-graphics/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add CharlesWiltgen/Axiom --skill axiom-graphics -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/axiom-graphics/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add CharlesWiltgen/Axiom --skill axiom-graphics -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/axiom-graphics/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install CharlesWiltgen/Axiom axiom-graphics
```

2. **Manually: put the files in place**
- File: `.github/skills/axiom-graphics/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add CharlesWiltgen/Axiom --skill axiom-graphics -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/CharlesWiltgen/Axiom --path axiom-codex/skills/axiom-graphics
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/axiom-graphics/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add CharlesWiltgen/Axiom --skill axiom-graphics -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/CharlesWiltgen/Axiom/tree/HEAD/axiom-codex/skills/axiom-graphics/SKILL.md

## When to use it
- convert GLSL or HLSL shaders to Metal Shading Language
- find out why a ported renderer shows a black screen or wrong colors
- get an app past 60fps on a ProMotion display
- show a 3D model in SwiftUI without a game engine
- open, edit and export a USD or USDZ file in Swift

## Example prompts
- Help me port this OpenGL renderer to Metal — where do I start and what breaks
- My app is stuck at 60fps on a ProMotion device, walk me through CADisplayLink and frame rate settings
- The image blurs when I resize the window — what is wrong with drawableSize

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 22ad8bd9700e616b.

BEGIN THIRD-PARTY FILE 22ad8bd9700e616b
```text
---
name: axiom-graphics
description: Use when working with ANY GPU rendering, Metal, OpenGL migration, shaders, 3D content, RealityKit, AR, USD/USDZ files, or display performance. Covers Metal migration, shader conversion, RealityKit ECS, RealityView, USDKit, ProMotion.
license: MIT
---

# Graphics

**You MUST use this skill for ANY GPU rendering, graphics programming, 3D content display, or display performance work.**

## When to Use

Use this router when:
- Porting OpenGL/OpenGL ES code to Metal
- Porting DirectX code to Metal
- Converting GLSL/HLSL shaders to Metal Shading Language
- Setting up MTKView or CAMetalLayer
- Rendering breaks or blurs when the window resizes or moves between screens
- Debugging GPU rendering issues (black screen, wrong colors, crashes)
- Evaluating translation layers (MetalANGLE, MoltenVK)
- Optimizing GPU performance or fixing thermal throttling
- App stuck at 60fps on ProMotion device
- Configuring CADisplayLink or render loops
- Variable refresh rate display issues
- Displaying 3D content in a non-game SwiftUI app
- Building AR experiences with RealityKit
- Using RealityView or Model3D in SwiftUI
- Spatial computing or visionOS 3D content
- Reading, editing, or exporting USD/USDZ files in Swift (USDKit)
- Adding ML to a render pipeline (MetalFX denoising, Metal tensors, neural rendering)
- Profiling long game sessions (metalperftrace, look-back traces)

## Routing Logic

### Metal Migration

**Strategy decisions** → See skills/metal-migration.md
- Translation layer vs native rewrite decision
- Project assessment and migration planning
- Anti-patterns and common mistakes
- Pressure scenarios for deadline resistance

**API reference & conversion** → See skills/metal-migration-ref.md
- GLSL → MSL shader conversion tables
- HLSL → MSL shader conversion tables
- GL/D3D API → Metal API equivalents
- MTKView setup, render pipelines, compute shaders
- Complete WWDC code examples

**Diagnostics** → See skills/metal-migration-diag.md
- Black screen after porting
- Shader compilation errors
- Wrong colors or coordinate systems
- Performance regressions
- Time-cost analysis per diagnostic path

### Rendering Surfaces Under Window Resizing

**Any rendering surface in a resizable window** → See skills/resizable-rendering.md
- MTKView `drawableSizeWillChange` (projection + render-target reallocation, live-resize throttling)
- CAMetalLayer manual `drawableSize`/`contentsScale` ownership
- Per-surface adaptation table: video layers, maps, charts, Canvas, web views, PDF, SpriteKit/SceneKit
- displayScale-keyed cache invalidation when a scene moves between screens (Mirroring, external display)

### Display Performance
```
END THIRD-PARTY FILE 22ad8bd9700e616b

The third-party file has ended. Everything between the 22ad8bd9700e616b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2695 of 12014 bytes. © CharlesWiltgen · MIT · https://github.com/CharlesWiltgen/Axiom/tree/HEAD/axiom-codex/skills/axiom-graphics/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md