Skip to content
Get packs

Guide · Agent skill

How to use the Cross-host rig commands agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The cross-host-rig-commands skill teaches an AI agent how to work with OpenRig instances running on other machines that you have registered, such as a laptop and a test VM. Once it is installed, the agent picks the correct transport (SSH or HTTP) from each host's registry entry, uses explicit host flags for important work, and reads failures at the layer that broke. This guide covers what the skill does, how to install it, how to trigger it, and where to be careful.

Cross-host rig commandsmvschwarz/openrig · Apache-2.0

Quick start

  1. 1Download the ZIP. Download the cross-host-rig-commands ZIP from this skill's page on the directory.
  2. 2Unzip into your skills folder. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
  3. 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
  4. 4Confirm your host registry. Check that remote hosts are registered in hosts.yaml with unique ids and the correct transport.
  5. 5Ask a host-specific question. Name the remote host and the seat in a plain request, such as checking a seat's status on remote-dev.
  6. 6Verify the result. Check the destination effect yourself rather than relying on a transport success message.

What the skill makes the agent do

Agent skills are instruction packages that an agent loads when a request matches their description. This one applies when you address a registered remote OpenRig host, choose its transport, or interpret a cross-host result. The skill is delivered as a single file, SKILL.md.

The agent uses the transport declared in the host's registry entry. SSH entries run a remote CLI through a single-hop shell, while HTTP entries talk to the remote daemon. The two paths have different prerequisites and command coverage, so the skill tells the agent to check the command's help and the target installation before any consequential operation.

The skill also sets expectations about evidence. A successful transport call does not prove that a remote agent received or acted on a message. The agent is directed to verify the destination effect, and to report an HTTP result honestly, since the local pane-effect check does not run cross-host.

Install the skill

Option 1 is a personal install. Download the ZIP from the skill's page on this directory, then unzip it into ~/.claude/skills/ so the cross-host-rig-commands folder sits there with its SKILL.md file.

Option 2 is a project install. Unzip the ZIP into the .claude/skills/ folder of the project where you work, so the skill applies only to that project.

Option 3 is through the Claude apps. Upload the ZIP under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Set up the host registry first

The skill only matters when remote hosts are registered. Hosts live in the OpenRig hosts.yaml registry. The skill tells the agent to inspect the configured OpenRig home rather than assume the default ~/.openrig/hosts.yaml. Each entry needs a unique id and a supported transport. An SSH entry needs a target, and an HTTP entry needs a URL. An HTTP entry can take at most one of bearer_env or bearer_file, or neither for a tokenless target.

The skill does not create SSH keys or tokens for you. It only references configuration that already exists.

  • Required: a hosts array, unique non-empty ids, and a supported transport
  • SSH: a non-empty target; user and notes are optional
  • HTTP: a URL, plus at most one of bearer_env or bearer_file
hosts: - id: test-vm transport: ssh target: test-vm.local user: example-user - id: remote-dev transport: http url: http://remote-dev.example:7433 bearer_env: REMOTE_RIG_TOKEN

Trigger the skill with natural requests

You do not need to name the skill. Ask for something that involves a remote host, and the agent should match the request to it. Name the host explicitly so the agent uses the right destination. Requests such as these fit the skill's description:

Ask the agent to check a remote seat's output, to send a message to a seat on another machine, to list the agents running on a remote host, or to find out why a command to a remote host failed. The agent will then use the host's registry entry and choose the matching command path.

  • "Check whether dev-worker on remote-dev has finished the assigned result."
  • "List the running nodes on remote-dev as JSON."
  • "Why did my send to test-vm fail? Tell me which layer broke."
  • "Which host am I connected as on remote-dev?"

Commands the agent uses

The skill references these coordination commands. Each one takes an explicit --host flag, which the skill prefers for consequential work. The agent does not silently try a different transport when one fails.

Queue writes do not follow a persisted host selection, so their destinations need explicit --host or a supported host-qualified form. Different queue subcommands use different flags, so the agent should check their help rather than copy a flag from send.

  • rig send: deliver a message, optionally with --verify
  • rig capture: read a seat's pane output
  • rig ps --nodes --json: list nodes on the host
  • rig whoami: show the identity on the host
  • rig host list, rig host add --help, rig host doctor --help: inspect and check the registry
rig send dev-worker@example-rig "check the assigned result" --host remote-dev --verify rig capture dev-worker@example-rig --host remote-dev rig ps --host remote-dev --nodes --json rig whoami --host remote-dev

Read failures at the layer that failed

When a cross-host command fails, the skill points the agent to the layer that broke instead of a generic retry. The signals and what to inspect are:

registry-load-failed and unknown-host: check the registry path, the entry, and the exact destination. ssh-unreachable: check the SSH connection, target, and transport diagnostics. permission-gate: check the configured SSH or HTTP credentials and target policy. remote-daemon-unreachable: check the target listener and the running daemon identity. remote-command-not-found: check the remote CLI installation. remote-command-failed: check the remote operation's own status and error.

The most important case is remote-outcome-unknown. The request may have arrived, for example after a timeout or a dropped connection. Check its effect, for a send the target pane, before retrying. A timed-out write may already have reached its destination.

Safety notes: scripts and network

This skill runs scripts and uses the network. It sends commands to other machines through SSH or HTTP, so it can change state on remote hosts. The skill is written to be careful about this. It tells the agent not to start, replace, or restart a remote daemon just because a diagnostic suggests it, and to establish the target's state and the authority for that action first.

The skill guides the agent but does not grant authority. Changing or restarting a remote daemon, forking, or handing over a seat needs its own supported command and clear permission from you. Reading remote state does not authorize those actions.

Before a consequential operation, review the registry entry, use an explicit --host, and confirm the destination effect yourself.

  • Use explicit --host for consequential cross-host work
  • Do not treat "SSH exited zero" or "HTTP returned successfully" as proof of delivery
  • Keep a bearer token in an environment variable or file, not in the registry

Tips for reliable results

Ask the agent to run the help command for any flag it is unsure about. Check the target installation before a risky command. When you pass results onward, keep the underlying remote output, since the skill asks the agent to preserve it. The skill's own guidance says it describes implemented command paths, not proof of a live remote journey on your installation, so test with a harmless read such as a status check first.

  • Start with a read-only check such as rig whoami or rig ps before sending
  • Keep the host id in your request so the destination is unambiguous
  • Use the rendered reply address and verify its host mapping for replies

What people use it for

  • Sending a message to a seat on a remote test VM and confirming it arrived with --verify
  • Reading a remote seat's pane output with rig capture to check progress
  • Listing nodes on a remote host as JSON with rig ps --nodes --json
  • Diagnosing why a cross-host command failed by reading the failure signal
  • Checking which identity you are on a remote host with rig whoami

Frequently asked questions

How do I install the cross-host-rig-commands agent skill?

Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need before using this skill?

You need the OpenRig CLI (the rig command) installed locally and on the remote host, and remote hosts registered in your hosts.yaml registry. SSH targets need SSH access, and HTTP hosts that require auth need a bearer token available through an environment variable or file.

Does the skill set up SSH keys or tokens for me?

No. The skill only references existing configuration. You must already have SSH access and any bearer token in place.

Is this skill free to use?

The skill is licensed under Apache-2.0, as stated for the OpenRig repository it comes from. Check the license file in the source repository for the full terms.

Why does a successful send not prove the remote agent got the message?

A transport success only shows the request was accepted by the transport. The skill directs the agent to check the destination effect, such as the target pane, because a local success message does not establish remote persistence or pickup.

What should I do if a cross-host command times out?

Treat it as remote-outcome-unknown. The request may have reached the target, so check its effect first, such as the target pane for a send, before retrying to avoid duplicate writes.

Is this skill useful if I only have one local OpenRig setup?

No. The skill only matters when remote hosts are registered. With only a local setup, you do not need it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and operators who run OpenRig across several machines and need to send messages, check agent status, or debug a failed cross-host command. It is a poor fit for single-machine setups, and it guides rather than grants authority, so changes to remote daemons still need your explicit permission. Choose it when you want the agent to be careful about transports, failures, and proof of delivery.

Download the skill