# Runai get cluster health summary

> Runai get cluster health summary is an open-source agent skill for health and science. Checks a Run:ai cluster's node health and scheduling, with a per-pool verdict. It is available on Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf and Goose.

- **Kind:** Skill
- **Pricing:** Open source
- **Platforms:** Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Goose
- **Website:** https://github.com/NVIDIA/skills/tree/main/skills/runai-get-cluster-health-summary
- **Repository:** https://github.com/nvidia/skills
- **GitHub stars:** 4,037
- **License:** Apache-2.0
- **Skill name:** runai-get-cluster-health-summary
- **Collection:** https://github.com/NVIDIA/skills
- **Categories:** health and science, cloud and infrastructure
- **Listing updated:** 2026-11-18

## About

This skill gives an admin a point-in-time read of a Run:ai cluster. It rates each node pool and the cluster as HEALTHY, DEGRADED or STUCK, and names the main blocker, such as NotReady nodes, GPUs that are offline, or a scheduler that is not placing work onto free GPUs. It separates a stuck scheduler from a pool that is simply full, and reports GPU counts, allocation, free capacity and the pending backlog.

The workflow resolves the cluster, collects pool, node, inventory and workload-count data in parallel, samples the oldest pending workloads, and classifies each one by reading its status, conditions and events. Verdict rules are fixed in the instructions, and the output lists the raw numbers behind each verdict. Recent cluster GPU utilization is included, and failed-workload counts are shown as context.

The skill is strictly read-only and works only through the Run:ai MCP server; it does not run kubectl or the runai CLI. It requires that MCP server to be connected and a cluster ID, or a choice among several clusters. Requests for cordon, drain, quota changes or other writes get no tool calls, and questions about quota, per-team GPU waste or XID errors are routed to other skills.

## When your agent uses it

> Point-in-time Run:ai cluster and node-health check: a HEALTHY, DEGRADED, or STUCK verdict per node pool with the dominant blocker — NotReady nodes, offline or failing GPU capacity, GPU counts, allocation vs utilization, the pending backlog, and a stuck scheduler vs a full pool. Use for "is the cluster healthy?", "is the scheduler stuck?", "any nodes down?", "are GPUs failing?", "how many GPUs are free?", "is the cluster saturated?", or "why isn't node pool X scheduling?". Not for quota fairness, team GPU waste, one workload, failed-workload node correlation, XID errors on one node, or writes.

## What it can access

From a static check of the files on GitHub; nothing was run.

- [Runs Python scripts](https://github.com/NVIDIA/skills/tree/HEAD/skills/runai-get-cluster-health-summary)
- [No network calls found in its scripts](https://github.com/NVIDIA/skills/tree/HEAD/skills/runai-get-cluster-health-summary)
- [License: Apache-2.0](https://github.com/NVIDIA/skills/tree/HEAD/skills/runai-get-cluster-health-summary)

## Features

- **Per-pool health verdict:** Rates each node pool and the whole cluster as HEALTHY, DEGRADED or STUCK with the reason.
- **Unhealthy node detection:** Lists NotReady or Unknown nodes with their conditions, taints and GPU counts.
- **Scheduler versus full-pool check:** Distinguishes free GPUs that are not being scheduled from pools that are genuinely at capacity.
- **Pending workload sampling:** Inspects the oldest pending workloads and classifies each by its block type.
- **GPU capacity and allocation:** Reports GPUs total, allocatable, allocated and free for each pool.
- **Read-only MCP workflow:** Uses only Run:ai MCP tools and never changes nodes, pools or workloads.

## Good for

- Check whether the GPU cluster is healthy right now
- Find out whether any GPU nodes are down
- See how many GPUs are free in each node pool
- Determine if the scheduler is stuck or pools are simply full
- Learn why a specific node pool is not scheduling work

## Install

### Claude Code

Copy the skill folder to `~/.claude/skills/runai-get-cluster-health-summary` to use it in all your projects:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/NVIDIA/skills.git "$tmp" &&
mkdir -p ~/.claude/skills &&
rm -rf ~/.claude/skills/runai-get-cluster-health-summary &&
cp -R "$tmp/skills/runai-get-cluster-health-summary" ~/.claude/skills/runai-get-cluster-health-summary &&
rm -rf "$tmp"
```

For one project only, put the folder in `.claude/skills/runai-get-cluster-health-summary` inside it instead.

### Codex

Copy the skill folder to `~/.agents/skills/runai-get-cluster-health-summary` to use it in every repository:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/NVIDIA/skills.git "$tmp" &&
mkdir -p ~/.agents/skills &&
rm -rf ~/.agents/skills/runai-get-cluster-health-summary &&
cp -R "$tmp/skills/runai-get-cluster-health-summary" ~/.agents/skills/runai-get-cluster-health-summary &&
rm -rf "$tmp"
```

For one repository only, put the folder in `.agents/skills/runai-get-cluster-health-summary` inside it instead.

### Cursor

Copy the skill folder to `~/.cursor/skills/runai-get-cluster-health-summary` to use it in every project:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/NVIDIA/skills.git "$tmp" &&
mkdir -p ~/.cursor/skills &&
rm -rf ~/.cursor/skills/runai-get-cluster-health-summary &&
cp -R "$tmp/skills/runai-get-cluster-health-summary" ~/.cursor/skills/runai-get-cluster-health-summary &&
rm -rf "$tmp"
```

For one project only, put the folder in `.cursor/skills/runai-get-cluster-health-summary` inside it instead.

### Gemini CLI

Run in a terminal (add `--scope workspace` to install it for the current workspace only):

```sh
gemini skills install https://github.com/NVIDIA/skills.git --path skills/runai-get-cluster-health-summary
```

Or copy the folder to `~/.gemini/skills/runai-get-cluster-health-summary` yourself.

### VS Code

For GitHub Copilot in VS Code, copy the skill folder to `~/.copilot/skills/runai-get-cluster-health-summary`:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/NVIDIA/skills.git "$tmp" &&
mkdir -p ~/.copilot/skills &&
rm -rf ~/.copilot/skills/runai-get-cluster-health-summary &&
cp -R "$tmp/skills/runai-get-cluster-health-summary" ~/.copilot/skills/runai-get-cluster-health-summary &&
rm -rf "$tmp"
```

For one project only, put the folder in `.github/skills/runai-get-cluster-health-summary` inside it instead.

### Other agents

Get the folder:

```sh
git clone --depth 1 https://github.com/NVIDIA/skills.git
```

Then copy `skills/skills/runai-get-cluster-health-summary` into your agent's skills folder as `runai-get-cluster-health-summary`. Agents that support SKILL.md read one folder per skill.

## FAQ

### What does this skill need to run?

It requires the Run:ai MCP server with read access. It does not use Kubernetes access, and if the MCP server is unavailable it stops rather than estimating numbers.

### Does it change anything in the cluster?

No. It is read-only, and requests to cordon, drain, restart, delete or rescale are declined with no tool calls.

### Can it tell whether GPUs are failing on a node that is Ready?

No. Node health at the MCP level cannot see a failing GPU on a Ready node, so that check is routed to runai-diagnose-node-health.

### Does it show failure history or trends?

Not failure history. The verdict is point-in-time, and capacity trends come from the cluster metrics tool over a longer window.

### How do I install Runai get cluster health summary in Claude Code?

Copy the skill folder from GitHub to ~/.claude/skills/runai-get-cluster-health-summary to use it in all your projects, or to .claude/skills/runai-get-cluster-health-summary in one project.

### Does Runai get cluster health summary run scripts?

Yes. It runs Python scripts. No network calls were found in its scripts. This comes from a static check of the files on GitHub; nothing was run. Read the files before you install it.

### Which AI agents can use Runai get cluster health summary?

Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf and Goose. Each reads skills in the SKILL.md format from its own folder; the install steps on this page list them.

### What are the best alternatives to Runai get cluster health summary?

The closest alternatives to Runai get cluster health summary are Gem devops guidelines, Azure developer CLI, Azure logic apps standard CLI, AWS resource query and AWS well architected review.

## Where this comes from

- Description: from the skill's own SKILL.md.

## Alternatives

- [Gem devops guidelines](https://ai-powered.com/skills/gem-devops-guidelines): Gem devops guidelines is an open-source agent skill for cloud and infrastructure.
- [Azure developer CLI](https://ai-powered.com/skills/azure-developer-cli): Azure developer CLI is an open-source agent skill for cloud and infrastructure.
- [Azure logic apps standard CLI](https://ai-powered.com/skills/azure-logic-apps-standard-cli): Azure logic apps standard CLI is an open-source agent skill for cloud and infrastructure.
- [AWS resource query](https://ai-powered.com/skills/aws-resource-query): AWS resource query is an open-source agent skill for cloud and infrastructure.
- [AWS well architected review](https://ai-powered.com/skills/aws-well-architected-review): AWS well architected review is an open-source agent skill for cloud and infrastructure.
- [Azure container registry CLI](https://ai-powered.com/skills/azure-container-registry-cli): Azure container registry CLI is an open-source agent skill for cloud and infrastructure.
- [AWS resource health diagnose](https://ai-powered.com/skills/aws-resource-health-diagnose): AWS resource health diagnose is an open-source agent skill for cloud and infrastructure.
- [Azure resource visualizer](https://ai-powered.com/skills/azure-resource-visualizer): Azure resource visualizer is an open-source agent skill for cloud and infrastructure.

---
Source: https://ai-powered.com/skills/runai-get-cluster-health-summary
