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, and stops if the installed
  CLI is older than the catalog contract this skill requires. 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, go to the contract check below. 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.

   **Then check the catalog contract.** Run:

   ```
   rocm fix --json
   ```

   It prints the catalog manifest as JSON and applies no fix. Read
   `contract_version` from that JSON and ignore the rest. Stdout holds only the
   JSON. Any `rocm:` notice goes to stderr. This skill requires
   `contract_version` 1 or higher.

   An older CLI rejects `--json` as an unexpected argument and exits with code 2.
   In [reference.md](reference.md), exit code 2 is a usage error such as an unknown fix id; here
   it means the CLI is too old. If the command exits with code 2 and an
   unexpected-argument error, or prints a lower `contract_version`, **stop**. Say
   that the installed `rocm` CLI is older than this skill requires, so the CLI is
   the side to update. Do **not** run `rocm examine`, `rocm diagnose`, or
   `rocm fix <id>`. Offer to update the CLI by re-running the installer above,
   with the user's consent, then repeat this check. If the user declines, the
   installer cannot run, or the check still fails afterwards (an older `rocm`
   earlier on `PATH` can cause that), hand the user the install page
   (https://github.com/ROCm/rocm-cli) and stop.

   Any other failure, such as a different exit code or output with no
   `contract_version`, is an error from the CLI and not proof that it is old.
   Relay the error text and stop, because reinstalling the same version would not
   clear it. Against a CLI without this contract, the entry ids, the
   auto-applicable set, and the exit codes this skill documents are guesses, and a
   guess presented as a fact is the failure this check prevents.

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

   ```

From amd/skills, MIT.

More from amd/skills