metal-kernel

Official PyTorch guidance for native Metal kernels and MPS operators on Apple Silicon.

metal-kernel is an official skill in the PyTorch repository. It is aimed at developers who need to add PyTorch operators to Apple's MPS backend, migrate existing MPSGraph implementations to native Metal kernels, or port CUDA-oriented logic to Apple Silicon. According to the provider, the intended approach is to use PyTorch's native Metal infrastructure under c10/metal rather than MPSGraph. This makes the skill a technical contribution guide for the PyTorch source tree, not a GPU driver, not a standalone Metal framework, and not a general introduction to machine learning.

Purpose and architecture

The workflow described by the provider connects three layers. First, native_functions.yaml must contain the correct dispatch mapping for the operator. During a migration, every relevant overload needs review, including functional, in-place, out, and Tensor or Scalar variants. The Metal kernel then belongs under aten/src/ATen/native/mps/kernels. For elementwise operations, the source describes functors and registration macros for unary, binary, and alpha-parameter cases. The third layer is the host-side stub under aten/src/ATen/native/mps/operations. It binds TensorIterator to the matching kernel library and registers MPS dispatch. This separation helps an engineer identify whether a failure belongs to YAML dispatch, Metal code, or host integration.

Practical implementation

According to the provider, REGISTER_UNARY_OP and REGISTER_BINARY_OP hide iterator plumbing for common elementwise operations. Depending on semantics, floating-point, integer, BFloat16, and complex data types may require separate registrations or functor overloads. The source explains operation-math and accumulation types, as well as precise mathematical helpers from c10/metal. Complex values deserve special attention because their Metal representations can be vector types. When migrating an existing MPSGraph operation, the old host implementation must be removed and every reference to the legacy function should be checked. Leaving one overload on the old path can make callers silently use MPSGraph even when another overload uses native Metal.

Testing and diagnosis

PyTorch's test infrastructure in test/test_mps.py checks basic output agreement. The skill also points to torch.mps.compile_shader, which can compile individual Metal shaders just in time and test them in isolation on an MPS device. The official documentation distinguishes threads as the total number of threads from group_size as the number of threads per threadgroup. This matters because dispatchThreads has different semantics from dispatchThreadgroups. For a multi-kernel pipeline, each intermediate result should be compared with a CPU or NumPy reference. Copying every GPU value to the CPU merely to perform an error check can introduce an avoidable synchronization cost.

Boundaries and safety

The skill assumes familiarity with C++, Objective-C or Objective-C++, Metal, PyTorch builds, and MPS. The referenced files are in the PyTorch source tree; they do not automatically change an installed PyTorch release. Apple hardware, a compatible operating system, compilers, SDKs, and a correctly configured build are required. The guide does not guarantee performance or numerical equality for every shape and data type. Empty and non-contiguous tensors, large tensors, index bounds, and asynchronous failures require particular care. According to the provider, errors should be reported through the supported MPS error buffer instead of forcing a GPU-to-CPU synchronization. Builds and tests belong in a controlled development workspace; unknown files, scripts, or generated changes must be reviewed before execution.

Source and classification

The primary source is https://github.com/pytorch/pytorch/tree/main/.claude/skills/metal-kernel. The complementary official PyTorch documentation at https://docs.pytorch.org/docs/stable/generated/torch.mps.compile_shader.html covers isolated shader testing. The PyTorch source tree is licensed under BSD-3-Clause. This catalog description was reviewed on September 9, 2026. GitHub stars are not stored for this entry because the Skill model has no github_stars field. The skill is compatible with Claude Code because it is published as a .claude/skills resource; the technical guidance still requires validation against the PyTorch version installed in the developer's environment.

Installation instructions

What it is and why it matters

metal-kernel is a PyTorch skill for writing native Metal and MPS kernels for Apple Silicon. It explains how to add new MPS support for PyTorch operators or migrate existing MPSGraph paths to native Metal kernels. According to the provider or the official project source, it is meant for cases where an agent should not only answer in general terms but work with concrete tools, files, or services. For beginners, the important point is that this is not a standalone chatbot. It is an instruction package or integration layer that gives an existing AI client additional capabilities.

The terminology matters. An MCP server exposes tools through the Model Context Protocol so a client can call them. A skill is usually a package of instructions, scripts, and references that tells an agent how to perform a repeatable task reliably. MPS is PyTorch’s backend for Apple Metal Performance Shaders; dispatch decides which implementation runs on a device. In both cases, the human still owns the goal, the permissions, and the review of the output.

Step 1: Requirements and setup

To get started, you need a compatible agent or client and access to the official source from PyTorch. You need a PyTorch development environment, Apple Silicon hardware or equivalent access, C++ and Metal knowledge, and familiarity with PyTorch operator registration. The skill points to native_functions.yaml, MPS operations, and Metal kernel directories. Follow the provider’s setup path closely, because small differences in paths, environment variables, authentication, or client configuration often cause confusing failures. Before connecting production projects, customer data, or live infrastructure, run a low-risk test with sample data and confirm that the client can see only what it should see.

After setup, document which client is used, where the configuration lives, and which permissions were granted. For local skills, record the installation path in the project or user profile. For an MCP server, record the server URL or start command, the transport method, and the authentication method. In a team, this prevents a working integration from later being reused with different rights, a different account, or an outdated version.

Security and best practices

Kernel code can introduce numerical errors, memory problems, or performance regressions. Use small test cases, compare CPU, CUDA, and MPS behavior where relevant, and cover every overload of an operator. Do not paste API keys, access tokens, database exports, confidential audio, or financial workpapers into a chat. Store secrets in environment variables, secret managers, or the secure configuration of the client. If a tool can perform actions, start in a test environment. For production systems, approvals, audit logs, and rollback paths matter more than the convenience of one fast prompt.

Good prompts define the goal, scope, and limits. Ask the agent to state assumptions, summarize risky actions before execution, and compare the result with the source data. For skills that include scripts, inspect what the script reads, what it writes, and which external services it contacts. That basic review lowers privacy risk and makes failures easier to trace.

Practical value, limits, and review

It helps PyTorch contributors connect dispatch definitions, host-side stubs, and shader implementations in a structured workflow. The greatest value appears when the task is repeatable and has clear review criteria. An agent can gather context, structure intermediate steps, and produce a usable format. Still, the first run should not be treated as final truth. Review samples, compare outputs with the official documentation or source data, and record which judgments were made by a person.

It is not meant for ordinary PyTorch users who only want to train a model. Without builds, tests, and review, the risk is high. The limits become visible with incomplete data, stale documentation, or tasks that have legal, financial, operational, or security impact. Provider claims describe what is technically possible; they do not automatically decide what is allowed or appropriate in your organization. Use metal-kernel as a controlled accelerator: start small, restrict permissions, review results, and only then move it into more important workflows.

Free
Provider
PyTorch
License
BSD-3-Clause
Last reviewed
09.09.2026

Repository and documentation

Categories

Compatible with

Claude Code