How to use the OpenRig Upgrade Helper agent skill

What the openrig-upgrade skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to follow a workflow. This one covers OpenRig CLI and daemon upgrades where live seats must keep running and each change must be verified.

The skill is built on one rule: the agent owns the sequence and stops after every mutation to observe the actual effect before choosing the next step. The skill deliberately has no end-to-end upgrade subcommand.

• Inspect the live host before changing anything.
• Choose one bounded mutation and state its expected effect.
• Make that single change, without bundling the next one.
• Check the process, listener, database, plugin and seat surfaces the change could have affected.
• Continue, adapt, or stop. A failed check is not a reason to retry blindly.

Install the openrig-upgrade skill in Claude

Download the ZIP from the skill page on this site. You can install it in one of three places, depending on whether you want it for yourself or for one project.

For a personal install, unzip the archive into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before the first upgrade

The skill assumes a working OpenRig setup. Confirm these requirements before asking an agent to upgrade anything.

• OpenRig CLI (rig) installed on the host
• Node.js, to run the helper scripts
• The sqlite3 command-line tool, for the database backup script
• Access to the OpenRig home directory, referred to as $OPENRIG_HOME

Use the helper scripts safely

The skill ships three helper scripts in its scripts/ folder. They print JSON and do not decide the upgrade sequence for the agent. The skill sets SKILL_DIR to the folder containing SKILL.md.

The inspect script asks the installed rig for its version, daemon status, node inventory and plugin inventory. A missing item stays visible with a suggested next probe. The backup script refuses to overwrite an existing destination, uses SQLite's backup operation and verifies the copy with an integrity check. It does not stop the daemon or restore a database. The plugin script compares the previous package, the target package and the live installed plugin. It never deletes a live file or overwrites a local change, and it reports conflicts for the agent to resolve.

• inspect-upgrade.mjs: reports current facts as JSON
• backup-sqlite.mjs: copies the database to a new file and runs PRAGMA integrity_check
• refresh-managed-plugin.mjs: plans refreshes, and applies only refresh-safe and add-safe files when given --apply-safe

Back up the database before any change

Take continuity snapshots first, then create a SQLite backup at a path outside the OpenRig home. Replace the placeholder rig ID and destination with your own values.

Keep seats alive and the rest of the host safe

Seats usually run in tmux and can survive a daemon restart. The daemon, database, wrappers and managed plugin files are the parts being changed. Running rig down tears down seats and is not part of a continuity-preserving upgrade.

Before the agent acts, name the rigs and seats whose continuity matters. On a production host, follow your normal operator process. On a recovery-friendly build VM, the agent may adopt a tested runtime directly but must still observe each step and stop on unexplained drift. The skill also covers handoffs when recovery crosses to another instance: record which executor and queue store own the recovery decision before any runtime change.

• Name the rigs and seats that must stay up before starting.
• Use rig down only if you intend to tear seats down.
• Stop on any unexplained difference from the expected result.