rocm-doctor
Diagnoses why ROCm, the HIP SDK, PyTorch, or llama.cpp is broken on an AMD GPU on Linux or Windows, then applies a low-risk fix with consent or hands back the exact next step. Also routes Lemonade, LM Studio, and Ollama problems to the right upstream channel. Use when the user reports that ROCm or HIP "isn't working", torch.cuda.is_available() is False, rocminfo / hipInfo can't see the GPU, or hits hipErrorNoBinaryForGpu, HSA_STATUS_ERROR_INVALID_ISA, "invalid device function", "no kernel image is available", cannot open /dev/kfd, permission denied on /dev/kfd, "ROCk module is NOT loaded", a missing libamdhip64.so / amdhip64_6.dll / hipblas.dll / vcruntime140_1.dll, an HSA_OVERRIDE_GFX_VERSION page fault, an iGPU+dGPU crash, a container that can't see the GPU, or an amdgpu-install / DKMS failure. Backed by the `rocm` CLI (`rocm examine` / `rocm diagnose` / `rocm fix`); this skill is a thin driver over those commands, not a re-implementation.
amd · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add amd/skills --skill rocm-doctor技能说明
name: rocm-doctor
description: >-
Diagnoses why ROCm, the HIP SDK, PyTorch, or llama.cpp is broken on an AMD GPU
on Linux or Windows, then applies a low-risk fix with consent or hands back the
exact next step. Also routes Lemonade, LM Studio, and Ollama problems to the
right upstream channel. Use when the user reports that ROCm or HIP "isn't
working", torch.cuda.is_available() is False, rocminfo / hipInfo can't see the
GPU, or hits hipErrorNoBinaryForGpu, HSA_STATUS_ERROR_INVALID_ISA, "invalid
device function", "no kernel image is available", cannot open /dev/kfd,
permission denied on /dev/kfd, "ROCk module is NOT loaded", a missing
libamdhip64.so / amdhip64_6.dll / hipblas.dll / vcruntime140_1.dll, an
HSA_OVERRIDE_GFX_VERSION page fault, an iGPU+dGPU crash, a container that can't
see the GPU, or an amdgpu-install / DKMS failure. Backed by the rocm CLI
(rocm examine / rocm diagnose / rocm fix); this skill is a thin driver
over those commands, not a re-implementation.
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 on native Linux or Windows?
If it is not — an NVIDIA / Intel / Apple GPU, or anything running under WSL2 — then stop and decline:
- Say plainly that it is out of scope for this skill and why (not an AMD GPU / WSL2 is a separate platform).
- 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 (or AMD's ROCm-on-WSL guide) 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 and the platform is native Linux or Windows. See Out of scope.
Prerequisites
- The
rocmCLI. This skill is only a driver over it; Phase 0 below installs it with the user's consent ifrocm --versionfails. Nothing else here is assumed — the CLI does the probing. - Platform: native Linux (in-tree
amdgpumodule +/dev/kfd) or Windows (HIP SDK). WSL2, NVIDIA/Intel/Apple GPUs, and clean-machine installs are out of scope (see Out of scope). - No fixed ROCm version, GPU arch (
gfx…), or container image is assumed —rocm examine/diagnosedetect the installed ROCm, the GPU'sgfxtarget, and container context, and match fixes to what they find. Never hand-setHSA_OVERRIDE_GFX_VERSION(or similar footgun env vars) yourself; let the CLI decide.
Workflow
Only start here once the Scope gate passes — the GPU is AMD and the platform is native Linux or Windows.
-
Ensure the
rocmCLI is present. Everything below shells out to it, so check first and install it if missing:rocm --versionIf 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
rocmandrocmdbinaries into~/.local/bin). Only nightly builds are published today, so install from thenightlychannel:- Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh -s -- nightly - Windows (PowerShell):
$env:ROCM_CLI_CHANNEL = "nightly" irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex
(Once rocm-cli cuts a stable release, drop the
nightlychannel —sh/iexalone will pull the latest stable build.)After install, confirm
~/.local/binis onPATHand re-runrocm --version. If it still isn't available, hand the user the install page (https://github.com/ROCm/rocm-cli) and stop. - Linux / macOS:
-
Diagnose. Pass the user's error text as the symptom:
rocm diagnose --symptom "<paste the exact error>" --jsonRead the JSON:
matched[]— ranked causes, each withid,title,score(0–100),evidence[], and afix(withfix_id,summary,commands,verify,notes, and theneeds_sudo/needs_reboot/needs_relogin/auto_applicableflags).score >= 75= high confidence;50–74= likely (confirm one more piece of evidence with the user first).out_of_scope— when set (e.g. WSL2), do not diagnose. 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) — those trackers apply regardless of platform. Otherwise relay theout_of_scopemessage and stop (see Out of scope).route_when_no_match— whenmatchedis empty, hand the user this upstream tracker; do not speculate. Note the CLI picks this target from the host-detected framework, not from the symptom text — so for an app named only in the symptom, route it yourself per Framework routing.
-
Propose the fix. Show the top match's
title,evidence, plan, andverifycommand. Only propose applying it when the user is on board. -
Apply with consent. For an auto-applicable fix:
rocm fix <f