How to use the Developing OpenRig agent skill

What does the developing-openrig skill make the agent do?

The skill is a map to the project's documentation and rules. When an agent works inside a clone of the OpenRig repository, it uses the skill to find which package or file owns a behaviour, choose which tests to run, test a change without disturbing the OpenRig daemon that runs its own session, judge whether a diff touches a high-risk area, and prepare a pull request.

The skill itself says the maps can be incomplete or stale, and that where a map and the code disagree, the code is right.

• Locate the package or file responsible for a behaviour
• Choose which tests to run before pushing
• Check whether a diff touches a high-risk area such as message delivery or migrations
• Prepare a pull request that follows the project's contribution rules

Install the developing-openrig skill from the ZIP

Download the ZIP from this page and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of two places, depending on how you want to use it:

Use a personal install by unzipping into ~/.claude/skills/. Use a project install by unzipping into the .claude/skills/ folder of a specific project. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.

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

How do you trigger the skill with a natural request?

You do not need a special command. The skill's description tells the agent when to use it, so ask for the kind of task it covers while you are working in your OpenRig clone. Requests such as the ones below match its purpose.

Be clear about the task type. If you ask about operating a rig or designing a rig topology, the skill's description says a different skill, openrig-skills, covers that, and this one does not apply.

• "Which package owns message delivery in this checkout?"
• "Which tests should I run for my change to the queue code?"
• "Test my change without restarting the daemon my session is running on."
• "Does this diff touch a high-risk area?"
• "Help me prepare a pull request for this fix."

What does the skill need before it works?

The skill assumes a working setup. It expects a local clone of the openrig repository and Node.js tooling for the repo's npm scripts. It also refers to the installed rig CLI and tmux, since it uses commands such as rig --version and rig daemon status to describe the running OpenRig.

• A local clone of the openrig repository
• Node.js tooling for the repo's npm scripts (npm run build, npm run lint, npm test)
• The installed rig CLI and tmux

How do you test a change without disturbing your own daemon?

The skill makes a key distinction. The installed OpenRig runs your session, while the checkout is the code you are changing. Restarting the installed daemon does not run your checkout, and stopping it stops the agents running on it, including you.

The skill directs the agent to the repo's own harnesses instead. The short version of the test step is the three npm scripts below. The scenario runner starts its own daemon and tmux server and drops your session's TMUX and daemon variables, so it does not touch the daemon your session runs on.

• Run npm run build, npm run lint and npm test for the short version
• Read docs/as-built/test-layers.md for the full ladder, including stub-agent scenarios
• A stub proves OpenRig's plumbing, not how Claude Code or Codex behave, so say which you exercised

What safety notes should you know?

The skill does not run scripts and does not use the network, according to its listing. Its main safety role is protecting the running OpenRig daemon during development. The most important point is the difference between the installed daemon and your checkout. Do not restart the daemon your own session runs on to test a change.

For changes to high-risk areas, the skill asks the agent to read the artery row in docs/as-built/arteries.md, describe the downstream effect in the pull request, and add or extend a stub-agent scenario, or explain why one cannot cover the change. The arteries list is incomplete by design, so absence from it does not make a change safe.

• Runs scripts: no
• Uses network: no
• Protect the daemon your session runs on
• Treat the arteries list as incomplete

Tips for getting the most from the skill

Start with the capability map before proposing something new. The skill advises checking what OpenRig can already do, and running rig --help to see the full command list, before deciding a command is missing. Check ROADMAP.md before proposing a feature.

Keep each pull request to one concern so the diff is reviewable in one sitting. If your change adds a refusal, prompt or required step, the skill points to CONTRIBUTING.md, which asks for the concrete case: who is harmed, how, and what it costs everyone else.

• Check the capability map and rig --help before proposing a new command
• Check ROADMAP.md before proposing a feature
• Keep one concern per pull request
• Fix a wrong map in the same pull request or open an issue