rocm-doctor

Files (5)

• .federated.json
• SKILL.md
• evals.json · evals/
• reference.md
• skill-card.md

SKILL.md (first lines)

# ROCm Doctor

Given a "ROCm / PyTorch / llama.cpp isn't working on my AMD GPU" complaint,
identify which **known misconfiguration** is the cause and either fix it (with
consent) or hand back the exact next step.

This skill does **not** probe or reason on its own. The `rocm` CLI owns the
probe, the closed failure-mode catalog, and the fixes; the skill just drives it
and relays the results. The catalog is a **closed list** — if the symptom
doesn't match a known mode, route the user upstream instead of guessing.

## Scope gate — check before anything else

Read the user's symptom and answer one question first: **is this an AMD GPU?**

If it is **not** — an **NVIDIA / Intel / Apple** GPU — then **stop and decline**:

- Say plainly that it is **out of scope** for this skill and why (not an AMD GPU).
- Give **no** troubleshooting for it: no commands to run, no driver or CUDA
  advice, no diagnostic checklist, no "try this first" — not even generic GPU
  suggestions. Point at the vendor's own docs and stop there.
- Do **not** run `rocm examine` / `rocm diagnose` / `rocm fix`.

Being helpful here means being honest about the boundary — confidently-wrong
advice for a stack this skill does not cover is worse than no advice. Only
continue past this gate when the GPU is AMD. See
[Out of scope](#out-of-scope).

**WSL2 is in scope** and does not stop this gate. It is a platform family of its
own, with its own catalog entries covering `/dev/dxg`, the DXCore handoff,
ROCDXG, the distro floor, the Windows host driver and WSL 1. Do not decline a
WSL2 user or route them away untouched — run the workflow as for any other
platform. The CLI scopes entries itself, so a bare-metal Linux fix is never
offered there.

## Prerequisites

- **The `rocm` CLI.** This skill is only a driver over it; Phase 0 below installs
  it with the user's consent if `rocm --version` fails. Nothing else here is
  assumed — the CLI does the probing.
- **Platform:** native Linux (in-tree `amdgpu` module + `/dev/kfd`), Windows
  (HIP SDK), or WSL2 (`/dev/dxg` + the Windows host driver). NVIDIA/Intel/Apple
  GPUs and clean-machine installs are out of scope (see
  [Out of scope](#out-of-scope)).
- **No fixed ROCm version, GPU arch (`gfx…`), or container image is assumed** —
  `rocm examine`/`diagnose` detect the installed ROCm, the GPU's `gfx` target, and
  container context, and match fixes to what they find. Never hand-set
  `HSA_OVERRIDE_GFX_VERSION` (or similar footgun env vars) yourself; let the CLI
  decide.

## Workflow

Only start here once the [Scope gate](#scope-gate--check-before-anything-else)
passes — the GPU is AMD. Linux, Windows and WSL2 all run the same workflow.

0. **Ensure the `rocm` CLI is present.** Everything below shells out to it, so
   check first and install it if missing:

   ```
   rocm --version
   ```

   If that succeeds, skip to step 1. If it's not found, install it **with the
   user's consent** (this fetches and runs an installer that drops the `rocm` and
   `rocmd` binaries into `~/.local/bin`). Both installers default to the
   `release` channel, so no channel argument is needed:

   - **Linux (x86_64 only):**
     ```
     curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh
     ```
   - **Windows (PowerShell):**
     ```
     irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex
     ```

   There is no macOS build. `install.sh` refuses anything but Linux x86_64, so
   on any other host hand the user the install page and stop rather than
   suggesting the command anyway. To pin an unreleased build instead, pass
   `nightly` (`sh -s -- nightly`, or `$env:ROCM_CLI_CHANNEL = "nightly"`).

   After install, confirm `~/.local/bin` is on `PATH` and re-run `rocm --version`.
   If it still isn't available, hand the user the install page
   (https://github.com/ROCm/rocm-cli) and stop.

1. **Diagnose.** Pass the user's error text as the symptom:

   ```
   rocm diagnose --symptom "<paste the exact error>" --json
   ```

   Read the JSON:
   - `has_match` — **the gate.** True means a cause cleared the threshold and
     you may propose a fix; false means nothing was established, so route
     upstream. Do **not** substitute "is `matched` empty?": several checkers
     open with a nonzero base score for a merely *potentially* relevant
     situation (a container, an APU beside a discrete GPU), so a healthy host
     still returns a non-empty `matched` of sub-threshold entries. Gating on
     emptiness proposes a fix for a machine with nothing wrong. True is not
     automatically the end of the question, either: a `diagnose-only` top
     match can clear the gate from host state alone, independent of whatever
     symptom was pasted — see the refinement in step 2.
   - `matched[]` — ranked causes, each with `id`, `title`, `score` (0–100),
     `evidence[]`, and a `fix` (with `fix_id`, `summary`, `commands`, `verify`,
     `notes`, and the `needs_sudo` / `needs_reboot` / `needs_relogin` /
     `auto_applicable` flags). `score >= 75` = high confidence; `50–74` = likely
     (confirm one more piece of evidence with the user first).
     **Read `fix.class` before you propose anything.** `diagnose-only` means
     the cause is real and explained but has no remedy — currently only
     `info-20-gpu-no-rocm-support`, which carries an `info-` id rather than a
     `fix-N` / `fix-wsl-N` one for that reason. `rocm fix` still takes that id
     and answers for it, by naming the problem and changing nothing.
   - `out_of_scope` — set only when the host's platform family has no catalog
     entries at all. Linux, Windows and WSL2 are all covered, so this does
     **not** fire for WSL2. When it is set, nothing was checked — say so rather
     than implying the machine looks fine. First, if the user's symptom clearly
     names an app that ships its own runtime (Lemonade, Ollama, LM Studio),
     route them to that app's tracker (see
     [Framework routing](#framework-routing)) — those trackers apply regardless

From amd/skills, MIT.

More from amd/skills