# moat-cuda-to-rocm

The moat-cuda-to-rocm skill for Claude Code ports CUDA projects to ROCm and HIP for AMD GPUs. The agent loads guidelines during migration planning, implementation, and code review.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 104 installs · ★ 510 repo stars
- Author: amd
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/amd/skills/tree/HEAD/skills/moat-cuda-to-rocm/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/moat-cuda-to-rocm

## What it does

The agent selects migration strategies for CMake or PyTorch builds, handles semantic differences between platforms, and checks wavefront portability alongside memory lifetimes. CDNA architectures feature a warp size of 64 while RDNA uses 32, requiring dynamic allocation sizing instead of hardcoded constants. Memory allocations on ROCm do not initialize to zero by default, so tracking read-modify-write sequences requires explicit initialization kernels.

The workflow covers library substitutions, warp synchronization masks, and stream lifetimes. The agent detects runtime faults that compile successfully on NVIDIA hardware but misbehave on AMD accelerators due to stricter validation rules.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add amd/skills --skill moat-cuda-to-rocm -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add amd/skills --skill moat-cuda-to-rocm -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add amd/skills --skill moat-cuda-to-rocm -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install amd/skills skills/moat-cuda-to-rocm
```

2. **Manually: put the files in place**
- File: `.github/skills/moat-cuda-to-rocm/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add amd/skills --skill moat-cuda-to-rocm -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/amd/skills --path skills/moat-cuda-to-rocm
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add amd/skills --skill moat-cuda-to-rocm -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/amd/skills/tree/HEAD/skills/moat-cuda-to-rocm/SKILL.md

## When to use it
- select the porting strategy for CMake or PyTorch builds
- configure wavefront size portability across CDNA and RDNA
- detect runtime faults caused by strict AMD memory validation
- replace warp synchronization functions and library calls

## Example prompts
- Port this CUDA project to ROCm and HIP using moat-cuda-to-rocm
- Review the codebase for AMD versus CUDA semantic differences with moat-cuda-to-rocm
- Determine the correct build strategy for the GPU migration

## 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: b54b9702b2477d02.

BEGIN THIRD-PARTY FILE b54b9702b2477d02
```text
---
name: moat-cuda-to-rocm
description: Port a CUDA project to ROCm/HIP for AMD GPUs. Strategy selection, the AMD-strict-where-CUDA-is-lenient fault classes, wavefront-size portability, library substitutions, and the validation bar. Use when planning, implementing, reviewing or validating a CUDA-to-HIP port, or when a HIP build compiles but misbehaves at runtime.
---

# CUDA to ROCm/HIP

Accumulated across many real ports. This file is the index and the decision-critical parts;
everything else is in `references/`, loaded only when you need it.

**Most porting bugs are not in symbol names.** Hipify handles the renaming. The bugs are
semantic differences where AMD is strict and CUDA is lenient, and most surface at runtime
on a build that compiled cleanly, though some, like a 32-bit `*_sync` mask, fail to
compile even after hipify runs clean. Read the fault-class index below before concluding a
port works.

## Naming: ROCm or HIP?

They name different things and reviewers notice.

- **HIP** is the programming model: the kernel dialect plus the `hipXxx` runtime API. The
  analogue of CUDA C++ and the CUDA runtime.
- **ROCm** is the platform: compiler, runtime, driver, and the roc*/hip* libraries. The
  analogue of the CUDA Toolkit.

So the CODE port is "to HIP" (hipify, the compat header, runtime symbols), while the
TARGET, build flag and libraries are "ROCm" (`USE_HIP`/`USE_ROCM`, "ROCm 7.2.1",
cuFFT -> hipFFT). A language+runtime port is precisely "a HIP port targeting ROCm". Never
call the platform "HIP" or the kernel dialect "ROCm". Details: `references/naming.md`.

## Which strategy

Classify the build first -- implementing the wrong strategy correctly is still wrong.

| build | strategy | shape |
|---|---|---|
| pure CMake | **A** (preferred) | one `cuda_to_hip.h` compat header, `enable_language(HIP)`, `set_source_files_properties(... LANGUAGE HIP)`; sources keep CUDA spelling |
| pytorch extension | **B** | rely on torch's build-time hipify; fix only what it cannot |
| anything else | neither | driver-API, runtime PTX, Go/cgo, qmake and codegen builds exist -- see the runtime-PTX fault class |

**How to tell:** look for `find_package(Torch)`, `torch.utils.cpp_extension`,
`CUDAExtension`, or a torch dependency in `setup.py`/`pyproject.toml`. If any is present it
is a pytorch extension -- Strategy B. Otherwise treat it as a pure CMake (or Makefile, or
meson) project -- Strategy A. The build system does not pick the strategy; what the sources
look like does. lc0 is meson and ports Strategy-A-shaped -- it just means writing by hand
what `enable_language(HIP)` would have given you, and `references/strategy-a-cmake.md` says
what.

Strategy A is the minimal-footprint model: the compat header is a no-op on NVIDIA, so the
CUDA build is untouched. Where the project includes CUDA headers by name, prefer the
**shim-header method** -- shadow headers on the HIP include path only -- which leaves the
```
END THIRD-PARTY FILE b54b9702b2477d02

The third-party file has ended. Everything between the b54b9702b2477d02 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 2941 of 15011 bytes. © amd · MIT · https://github.com/amd/skills/tree/HEAD/skills/moat-cuda-to-rocm/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
