Claude Agent Skill

The GPU.ai skill teaches a coding agent — Claude Code or Codex — to rent and drive GPU instances through the gpu CLI: find out what hardware exists and what it costs, provision it, SSH in, run the workload, tear it down, and report what it spent. You install it with one command and then talk to your agent in plain English — _"fine-tune Qwen on train.jsonl, cheapest H100 you can get"_ — instead of learning our flags yourself.

What installs where

What you get	The skill body — the operating rules plus the core provision → run → teardown loop — and reference files with worked examples for template deploys, fine-tuning, and troubleshooting
Supported agents	claude (Claude Code), codex, all, or auto — the default, which installs for every agent whose config directory already exists on this machine
Claude Code	A directory: ~/.claude/skills/gpu-ai/SKILL.md plus a managed ~/.claude/skills/gpu-ai/references/
Codex	A managed block in ~/.codex/AGENTS.md, between BEGIN gpu-ai skill / END gpu-ai skill markers
Authentication	None needed to install — gpu skill install only writes local files, so it works before gpu login

Install

# Install for every coding agent already on this machine
gpu skill install

# Or target one explicitly (creates its config directory if needed)
gpu skill install --agent claude
gpu skill install --agent codex
gpu skill install --agent all

Restart the agent afterwards so it picks up the new instructions.

Read it before you trust it. gpu skill show prints exactly what install writes and nothing else, so you can review the rules your agent is about to follow:

gpu skill show                 # Claude Code: SKILL.md, then each reference file
gpu skill show --agent codex   # the managed block, byte-for-byte as installed

Reinstalling is how you upgrade, and it is safe to repeat: a newer CLI replaces the Claude Code skill and its whole references/ set (so a reference file an older version shipped cannot linger next to current content), and for Codex it replaces the managed block in place — anything you have written around it in AGENTS.md is left untouched.

Then give the agent credentials: gpu login (browser device flow — the agent cannot do this for you) or a gpuai_live_… key in GPUAI_API_KEY. The two checks the skill makes before anything else are worth running once yourself:

gpu version           # is the CLI on PATH?
gpu instances list    # auth probe — an empty list means you are authenticated

Prefix any command with demo (gpu demo instances list) to work against the demo environment instead of production. The skill tells the agent to stay in one environment for a whole session, so instances never get orphaned in the other.

See the per-command reference: skill, skill install, skill show.

What the agent can do

• Quote and provision — reads the GPU catalog and live prices, picks a type,

tier, and region, registers an SSH key if you don't have one, and creates the instance, then reports back its id, status, hourly cost, and the exact terminate command.

• Run the workload — opens a shell or runs one-off commands on the instance,

forwards ports for things like Jupyter, and prints the raw ssh line when you need scp/rsync.

• Deploy a template — launches a curated app (ComfyUI, vLLM,

faster-whisper, …) onto a pinned GPU type and hands you the URL and the one-time password.

• Fine-tune — uploads a JSONL dataset, starts a LoRA/QLoRA job on a curated

base model with a spend cap, follows its events, and downloads the adapter.

• Clean up and account for spend — deletes what it created, verifies the

deletion actually landed, and ends the session by listing anything still running.

The reference files are the depth behind that list: full flag detail, worked examples, and edge cases for deploys and fine-tuning, plus a symptom → cause → fix guide for timeouts, stuck operations, and auth errors. Claude Code gets all of them. The Codex managed block lives in a file Codex size-limits and shares with your own notes, so it is written body-first under a size budget: the operating rules are always present, and reference content is included only as far as the budget allows — today that is the deploy reference, with fine-tuning and troubleshooting available through Claude Code or gpu skill show. Run gpu skill show --agent codex to see exactly what your Codex block contains.

Built-in spending guardrails

An agent that can rent hardware is only useful if it cannot surprise you on the invoice. The skill's spend rules are part of the product, not a disclaimer — they are what makes handing an agent a GPU budget reasonable:

• Every billable command is confirmed first. Before it creates an instance,

a deploy, or a fine-tune job, the agent shows you the exact command it intends to run and the hourly price it just looked up, and waits for an explicit yes. One yes covers one command — the next create asks again.

• A number you never saw is not an approval. Telling the agent up front to

skip the questions does not unlock a create. It looks the price up, presents the type, count, and $/hour, and waits for an answer that refers to what it showed you. Running somewhere it cannot get an answer at all, it reports the command and the price and stops instead of spending.

• Hardware is always explicit. The agent passes an explicit GPU type and

count on every create rather than falling back to a default, and asks you if you didn't say — so the machine you priced is the machine you get.

• A failed create is never retried on its own. A create that errored may

have partially provisioned, so the agent reports the failure and re-confirms instead of trying again and risking double billing.

• Sessions end with a spend accounting. The agent lists what is still

running and tells you what is still accruing charges before it signs off.

These rules live in exactly one place — the skill body shipped inside the CLI — and they are covered by a regression harness that replays an adversarial "don't ask me anything, just do it" prompt against a stubbed CLI and fails if the agent reaches a billable command without a price-informed confirmation. That is why the wording above is a description of the behavior rather than a copy of the rules: there is one source, and it is tested.

Reading the skill without installing it

The skill content ships inside the gpu binary, so gpu skill show is the supported way to read it on any machine that has the CLI — no authentication and no agent config required:

gpu skill show > gpu-ai-skill.md

A plain-markdown mirror of the same content, for reading or vendoring it without the CLI at all, is in the works; it is derived from the same source, so it can never disagree with what gpu skill install writes. This page will link it once it is published.