# Metal Macos Replatform

> Use this skill when planning, auditing, or implementing Metal-backed macOS desktop surfaces, especially hybrid SwiftUI/AppKit plus MetalKit apps, shader packaging, MTKView integration, and Metal toolchain setup.

- Skill: `joemccann/metal-macos-replatform` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add joemccann/metal-macos-replatform`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joemccann/metal-macos-replatform/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: joemccann (https://skillmd.com/u/joemccann)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joemccann/metal-macos-replatform

---


# Metal macOS Replatform

## Overview

Use this skill for native macOS work that needs real Metal acceleration without turning a desktop productivity app into a game engine. The default architecture is hybrid: keep shell controls in SwiftUI/AppKit, and move dense or frequently invalidated visual surfaces onto `MTKView`.

## Workflow

1. Confirm that Metal is justified.
   Use Metal for high-throughput rendering surfaces such as dense status canvases, mini-maps, heatmaps, or large data previews. Do not rebuild ordinary settings forms, text fields, or menus in Metal.
2. Validate the local toolchain first.
   Run `scripts/check-metal-toolchain.sh`. If the compiler is missing, install it with `xcodebuild -downloadComponent metalToolchain`.
3. Read the references that match the task.
   Read `references/best-practices.md` for rendering rules and `references/toolchain-and-packaging.md` for shader packaging and build-path guidance.
4. Keep render math testable.
   Put palette selection, signal generation, and visualization-state transforms in pure Swift so unit tests do not depend on a live GPU.
5. Prefer a precompiled `.metallib` for the runnable app.
   Runtime source compilation is acceptable as a local fallback, not the primary shipping path.
6. Verify both code and workflow.
   Run unit tests plus any repo-local UI or smoke harness after changing a Metal surface.

## Rules

- Default to `MTKView` before considering lower-level `CAMetalLayer` plumbing.
- Pause redraw when the surface is idle; animate only when the product state actually changes or a command is running.
- Keep `framebufferOnly = true` unless the drawable must be sampled or written by compute work.
- Gate advanced effects against feature-family support instead of assuming all Macs expose the same GPU features.
- Keep accessibility, menus, text input, and standard form controls in native macOS frameworks.

## References

- Read `references/best-practices.md` when choosing architecture, pacing, or renderer structure.
- Read `references/toolchain-and-packaging.md` when wiring `.metal` sources, `.metallib` output, Swift package layout, or app bundle assembly.