AQUA FIELD GUIDE
Aqua field guide · AI agent guide

Your coding agent,
taught the Aqua workflow.

One shared skill that lets Codex, Claude Code or Copilot prepare, submit, monitor and check your Aqua PBS jobs—following the same rules every time, within the scope and budget you set.

Codex + Claude Code + CopilotPBS · Pixi · ROS · PythonReviewed 28 September 2026
Start here / How the agent support works

What the skill adds to your agent.

A coding agent can already read your code, edit files and run commands such as ssh. The aqua-hpc skill is a folder of instructions it loads when you ask for Aqua work. It tells the agent how Aqua differs from your laptop: where work may run, what every submission must include, and what counts as a finished experiment.

01 / YOUR COMPUTER

The agent runs here

It reads your project, writes job scripts and a run manifest, and reaches Aqua through the SSH access you already have. Nothing is installed on Aqua.

02 / AQUA LOGIN NODE

The agent administers here

Staging files, submitting with qsub and reading qstat. Short, lightweight commands only—never the workload itself.

03 / COMPUTE NODES

PBS runs your work here

The scheduler starts each job when resources are free. The agent checks logs and outputs afterwards and reports what it found.

The skill does not give you access.

It does not create an HPC account, choose or authorise an RPID, configure SSH, or override your agent’s permission settings. You need working Aqua access first. QUT’s Aqua documentation and job submission guide are authoritative; Aqua basics walks through a first job by hand.

What is in the toolkit?
SKILL.md
The short workflow the agent follows. It is loaded whenever the skill is invoked.
References
Detail the agent reads only when relevant: RPID & PBS, environments, experiments, ROS, queues & walltime, operations, recovery and common requests.
Installer
scripts/install_skills.py copies the skill into a project for your chosen agent. Set it up.
Example
A tiny eight-cell CPU matrix for trying a bounded campaign end to end.
How it works / What the agent does

The same seven steps, every time.

When you ask for Aqua work, the skill has the agent follow this sequence. Each step leaves evidence you can check. You decide how far it goes: preparation only, one smoke test, or a full campaign.

  1. Establish the run

    SSH alias, remote workspace, authorised RPID, input locations, resource budget and which actions you allowed. It reuses answers you already gave instead of asking again.

  2. Know where each command runs

    It separates local preparation, lightweight login-node administration and scheduled compute, and discovers qsub, queues and storage rather than assuming them.

  3. Account for the project

    Every submission carries a real RPID—never a placeholder, and never the old no-RPID grace period. RPID and PBS rules.

  4. Stage a fixed snapshot

    It copies one version of your code into a new run directory and records the revision, lockfile hash, flags and data identity, so queued jobs never read a checkout you are still editing. It checks for fixes made on Aqua before syncing over them.

  5. Prove one case first

    It preflights the real environment on a compute node, then runs one representative case before scaling. See environments, experiments and ROS.

  6. Submit and record

    It saves each PBS job ID immediately, and keeps accepted, queued, running, exited 0 and scientifically complete apart. Success means the expected outputs exist and check out.

  7. Monitor and recover within limits

    It batches SSH queries, reuses one watcher, and retries only within the caps you set. When the evidence needs you or an operator, it stops and says so. Operations · recovery.

Every report says what actually happened.

What was changed or submitted, job IDs, observed state, output locations, validation evidence and open issues. The agent never infers success from empty output, a missing queue entry or a successful SSH login.

How it works / Scope and guardrails

You set the scope. The agent stays inside it.

Your wording is the authorisation. Preparing work does not permit submitting it, and a status question does not permit retries or cancellation.

You ask The agent may It will not
“Prepare it; do not submit yet.” Inspect the project, write scripts, stage a preview. Submit anything.
“Run a smoke test under my RPID.” Submit one small job and check its output. Launch the full matrix.
“Submit these 12 cells, max two at once.” Submit, record every ID, validate each output. Exceed the concurrency or tested resources.
“Update?” Take one fresh, read-only status snapshot. Start another watcher, retry or cancel.
“Fix errors; one retry, up to 32 GB and 4 h.” Diagnose, fix in a new snapshot, retry each failed cell once. Change scientific settings or go past the cap.

Once you have authorised an action and its budget, the agent won’t ask for the same permission again. Your agent’s own tool prompts still apply.

Let one agent own submissions for each campaign. If you switch agents, hand over the run record—run path, code/lock/data hashes, config, manifest, PBS IDs, last known state and remaining work—but never secrets.

Set up / Install the skill

Install once per project.

You need Python 3, Git, a coding agent and SSH access to Aqua that already works. The agent runs on your own computer.

  1. Get the toolkit

    On your own machine · get the toolkit 
    git clone https://github.com/margauxmedwards/aqua-hpc-skills.git
cd aqua-hpc-skills

    Clone the default branch.

  2. Install the skill into your project

    Pick your agent and run this from the toolkit folder. Replace /path/to/your/project with your experiment’s folder on your computer, not on Aqua.

    Install for Codex · from the toolkit directory 
    python3 scripts/install_skills.py --agent codex --project /path/to/your/project

    Installed into .agents/skills/aqua-hpc in your project. Start or reload Codex there, then mention $aqua-hpc.

    The installer never overwrites an existing copy and does not set up SSH or cluster permissions. Updating? See keep things current.

  3. Start with a plan, not a submission

    First prompt · fill in your own paths and budget 
    $aqua-hpc Inspect this project's runner, flags and environment.
Use my SSH alias [alias], remote workspace [path], and authorized RPID [ID].
Prepare a representative smoke test before the full experiment.
Budget: [CPUs / RAM / GPUs / walltime], [N] concurrent jobs.
Show me the concrete run configuration; do not submit yet.

    When the plan looks right, change the last line to authorise submission. The agent won’t ask again for permission you have already given.

New to coding agents? AI4Coding: getting-started tips covers context, prompts and defining success (repository).

Reference / Common requests

A practical prompt cookbook.

Use these in Codex, Claude Code or Copilot with the Aqua skill loaded. Each response should distinguish observations, proposed actions and work actually completed.

“Is the HPC working?”
Read-only health check

Ask for separate checks of login, scheduler and queue health, plus the observation time. A login success alone does not establish compute health.

Checked at [time]: login reachable; PBS responsive; [queue] enabled and started. Compute execution not tested.

A failed scheduler query means unknown or unresponsive, not necessarily a cluster-wide outage. “Schedule a small test under my RPID” separately authorizes a compute smoke job.

“Run this experiment for me on the HPC.”

Provide the entrypoint/config, inputs, RPID, remote path and resource budget. Ask for one representative smoke case before the approved matrix.

Run this manifest on Aqua under my recorded RPID. Maximum two concurrent jobs; use the measured resource request. Validate a smoke case first, then submit the eight cells and save their IDs.

Expect the submitted IDs, selected route/placement, per-job resources, output path, smoke evidence and observed state. No job ID should be invented when a submission is unresolved.

“Which queue and walltime should I use?”
Compare QCR and general placement for this experiment. Check my eligibility, tested GPU requirements and current limits. Estimate walltime from representative runs and state queue-wait uncertainty.

Expect a recommendation with evidence. QCR membership, project accounting and hardware compatibility are separate. A job that needs 60 hours without checkpoints will not fit a 48-hour queue. Background: queues and walltime.

“Update?” / “How are my experiments going?”
One fresh snapshot
As of [time], 3/8 cells are validated: 1 running, 1 queued, 2 failed, 1 not submitted. The running cell is at 50/100 records. One failed cell exited zero but produced 0/100 outputs. ETA unknown.

This is an illustrative response, not current job status. Counts should reconcile with the original manifest; attempts should not inflate cell counts. Stale data and unverified outputs must be labeled.

“Can you poll my HPC experiments?”
Monitor these recorded jobs every 10 minutes for up to an hour, or until all are terminal. Reuse any existing monitor. Report failures and incomplete outputs; do not retry jobs automatically.

Expect the actual monitor/session identity, interval, deadline, last observation and available delivery channel. A tool must not promise chat notifications unless that capability is configured. “Update?” should not create a second watcher.

“Stop polling, leave the experiments running” stops only that monitor, not PBS jobs or shared SSH connections.

“Have there been errors? Check and fix them.”
Inspect the recorded jobs, logs and expected outputs. Fix diagnosed causes in a new snapshot, validate a representative case, and retry terminal failed cells within our existing budget. Preserve successful cells and live jobs.

Expect the evidence, actual fix, validation result, old→new job mapping and remaining issues. An environment repair should not silently change model, sensor, precision or sampling choices.

“If it hits memory or walltime, requeue with more.”
Allow at most one resource-recovery retry per failed cell, up to 32 GB host RAM and four hours, maximum two concurrent. Preserve the scientific configuration. Confirm the original job is terminal and no replacement is running before submitting.
Failure What helps
Confirmed host RAM limit Measured RAM increase within the cap. A cap is not the original request.
CUDA / GPU out of memory Investigate VRAM; more host RAM does not add device memory.
Walltime limit with progress Enough time for a full restart, or a verified compatible checkpoint.
Disk, inode or quota exhaustion Storage diagnosis and scoped recovery, not extra RAM.
Unknown state or submission timeout Reconcile the original job; do not create a possible duplicate.

Stop at the agreed retry/resource limits. A replacement usually gets a new PBS ID; more walltime does not automatically resume prior work. Recovery rules and evidence.

These formats were exercised in 14 synthetic scenarios with both Codex and Claude, with targeted recovery retests. Read the responses and evaluation notes.

Reference / Updates and maintenance

Make updates deliberate.

When QUT changes a requirement

  1. Check the official notice, effective date and affected jobs.
  2. Update the shared submission wrapper and all exceptional paths, including retries and interactive sessions.
  3. Validate a small job and inspect its recorded accounting/resources and outputs.
  4. Record the date and evidence in the shared references. Distinguish policy from a cluster snapshot.
  5. Update the hand-run examples in RPID page too.

When this toolkit changes

  1. Check local changes with git status, then fetch and inspect the update.
  2. On the intended branch, use git pull --ff-only when your working tree is ready.
  3. Compare skills/aqua-hpc against your project’s installed copy. Preserve local customizations.
  4. Move the old installed folder to a backup outside the agent’s skill-discovery folder, then rerun the installer.
  5. Restart/reload the agent and try a read-only health or planning prompt.

Move the old installed copy aside before reinstalling, retire any old copied Copilot instructions, and never change files that queued or running jobs are using.

For the RPID requirement, the RPID page has a ready-made prompt that asks your agent to update every submission path.

Reference / Sources and limits

Sources and limits.

Official QUT guidance takes precedence over this community guide:

The RPID deadline comes from QUT’s notice, and the RPID format from Aqua’s scheduler. Queue details come from read-only scheduler queries on 28 September 2026. The example matrix was tested against simulated PBS; a live array with a valid RPID and automatic recovery are not yet verified.

Full source and maintenance notes · Codex skills · Claude Code skills · Pixi run