# Hpc

> Launch and manage jobs on the HPC cluster (INVOKE ONLY when the user explicitly runs /hpc or asks to use this skill).

- Skill: `lacerbi/hpc` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lacerbi/hpc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lacerbi/hpc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lacerbi (https://skillmd.com/u/lacerbi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lacerbi/hpc

---


# /hpc — launch work on the HPC cluster

You run the `hpc` launcher yourself to put the user's work on the cluster. That is
the point of the tool — do not hand commands to the user to run, unless asked.

## 1. Find the launcher

1. Look for its path in the user's global `~/.claude/CLAUDE.md`, under an
   `## hpc-launcher location` heading.
2. If it isn't there, discover it: run `command -v hpc` with the **Bash tool**
   (Git Bash) and take the directory of that path. If that fails, ask the user
   where the `hpc-launcher` folder is.
3. Record it so later calls skip discovery — append to `~/.claude/CLAUDE.md`:

   ```
   ## hpc-launcher location
   The `hpc` launcher (for the /hpc skill) is at: `<path>`
   ```

   Keep `<path>` `~`-relative when it's under home — that file is public, so a
   machine-specific absolute won't travel (and needlessly shows the username).

## 2. Read the launcher's own docs

- `<path>/README.md` — what it does, setup, every command. **Always.**
- `<path>/clusters/<HPC_CLUSTER>.md` — facts for the cluster this repo targets
  (`HPC_CLUSTER` in `.hpc.env`; `hpc clusters` lists them). Read it when running or
  configuring a job — partitions, filesystem, gotchas (e.g. Roihu's split login
  hosts + 24 h SSH cert).
- `<path>/AGENTS.md`, `DESIGN.md`, `TODO.md` — only when you need rationale,
  limitations, or current status.

Read the live files. Do not rely on remembered defaults (partitions, modules,
torch module/wheel, walltimes) — they live in the cluster's `clusters/<name>.env`
profile and `hpc-env.example`, not in your memory.

## 3. Run it yourself

- `hpc` is bash; use the **Bash tool** (Git Bash / MSYS), not PowerShell.
- Execute the commands directly — `hpc run`, `hpc test`, `hpc status`, `hpc logs`,
  `hpc collect`, `hpc upload`, `hpc wait`, `hpc init`, etc. Don't delegate them to
  the user. (For unattended/scripted use, `hpc wait` blocks until a job is done and
  exits its rc, and `hpc status --json` / `hpc logs --once` are non-interactive —
  see the README.)
- Auth: the user's ssh-agent holds the cluster key. If an `hpc` call fails on SSH
  auth, ask the user to load it once (`ssh-add` their key), then keep running the
  commands yourself.
- A project needs a `.hpc.env` (run `hpc init`) before `hpc run` / `hpc test`.
- `hpc cancel` refuses to kill a RUNNING job unless you pass `--force`. If you were
  only cancelling because the job was stuck in the queue, the refusal means it has now
  started — so the reason to cancel is gone; let it run. Only `--force` if you'd kill
  it regardless of queue state (bugged code, wrong config, superseded run).

## 4. Carry out the user's request, following the docs you just read.