How to use the Live Rig Topology Changes agent skill

What this skill makes the agent do

The skill is for changing a rig while it is alive, without rebuilding the whole topology. It tells the agent which OpenRig commands fit each change: rig grow for simple seat additions, rig expand or rig add when a fragment is needed, rig shrink and rig remove for removing capacity, rig launch for relaunching a node, and rig bind, rig adopt and rig attach for connecting existing sessions to OpenRig identities.

The skill also tells the agent what to check afterward, such as whether rig whoami and rig ps --nodes reflect the new state, and it lists four common failure modes to avoid.

Install the skill from the ZIP or the Claude apps

Download the ZIP from this page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. For one project only, place it in that project's .claude/skills/ folder. The skill's file is SKILL.md.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you start

The skill only makes sense against a working OpenRig installation. You need the OpenRig CLI and daemon installed, because the rig commands only work against an OpenRig daemon and its rigs. You also need a running rig to change. The session-binding commands imply that tmux is required.

Do not use the skill to create a rig from scratch. For that, use rig up, which is a lifecycle command rather than a mutation.

• OpenRig CLI and daemon installed (rig commands available)
• A running OpenRig rig to mutate
• tmux, implied by the session-binding commands

Ask for a change in plain language

You do not need to name the skill or the commands. Describe the change you want and name the rig. The skill applies when your request involves changing a live rig. Good requests name the operation and its scope, so the agent knows which rig and seats are affected.

Before any change to a live rig, the skill expects the agent to name the operation's owner and scope, record the topology before and after, and keep any state needed for recovery.

• Add two reviewer seats to the running rig called review-rig.
• Remove the idle seat qa-2 from pod backend and confirm no references to it remain.
• Adopt the existing tmux session dev-main into the logical node builder in this rig.
• Attach my current shell to the node lead in rig ops-rig as an observer.
• Relaunch the node researcher in the running rig and check that rig ps shows it.

Pick the right command for the change

For the simple case, rig grow adds one or more seats without writing YAML. Each seat gets the default agent spec and its default profile. Check rig grow --help on your installed version, because the skill notes that this command was added after the v0.2.0 CLI reference.

Write a fragment instead when a seat needs something rig grow does not set, such as an explicit model, a permission policy, a different agent spec or role profile, a per-seat runtime or working directory, or startup files. Use rig expand to add a pod, or rig add to add one member to an existing pod.

• rig grow <rig-id> <member...> : add seats with defaults; options include --pod, --new-pod, --runtime, --cwd and --json
• rig expand <rig-id> <pod-fragment-path> : add a pod from a fragment
• rig add <rig> <pod-namespace> <member-fragment-path> : add one member to an existing pod
• rig shrink <rigId> <podRef> and rig remove <rigId> <nodeRef> : remove capacity
• rig bind, rig adopt and rig attach --self : connect existing sessions to logical nodes

Verify the change on the active rig

A passing schema check or an isolated test fixture does not prove that an existing live rig was changed correctly. The skill asks for proof on the active rig, because clean fixtures miss the failure modes that appear in live topologies.

After each change, the agent should confirm the result. For a new seat, the queue, startup context and role should exist and rig whoami should resolve the seat. For a removal, stale references should be gone. For an adopted session, rig whoami should report it correctly. Observer attachments should be recorded, and rig ps --nodes should reflect the current state rather than a cached earlier view.

• Add seat: new seat has queue, startup context and role; rig whoami resolves it
• Remove seat: stale references cleaned; edges and permissions updated
• Adopt session: tmux session bound at the OpenRig identity layer; rig whoami reports correctly
• Attach observer: external CLI attachment recorded
• After every move: rig ps --nodes reflects current truth

Avoid the four failure modes

The skill names four failures to watch for. A new seat can lack the queue, startup context or role files it needs, even though the tmux session exists. Edges and permissions may not be updated when a seat is added or removed, so later workflows can route to seats that no longer exist. An adopt or bind can succeed at the tmux layer without succeeding at the OpenRig identity layer, so rig whoami does not know about the session. Shrink or remove can leave stale topology references that later workflows route into.

Cleanup is part of the operation, not an optional follow-up. Treat a removal as incomplete until the references are checked.

• New seat lacks queue, startup context or role files
• Edges and permissions not updated after add or remove
• Adopt or bind works in tmux but not in OpenRig identity
• Shrink or remove leaves stale topology references

Understand the safety limits

This skill runs no scripts and makes no network calls, according to its listing. The risk is in what the commands do to a working system. Running them on a live rig can change or remove working agent sessions, so the agent should act only on a rig you own or have explicitly authorized.

Replacing the occupant of a seat while keeping its continuity is a different task. The skill points to the seat-continuity-and-handover skill for that. Scaling specialized capacity is covered by seat-scaling-and-specialization.

• Runs scripts: no
• Uses network: no
• Changes apply to live sessions; act only on an authorized rig
• Use seat-continuity-and-handover to replace an occupant on a stable seat