developing-openrig skill
✓ VerifiedProvides guidance for contributing to the OpenRig source code, including navigating architecture, testing changes, and preparing pull requests.
- GitHub stars
- 8,830
- Files
- 1
- Last commit
- Nov 12, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the developing-openrig skill do?
developing-openrig provides guidance for contributing to the OpenRig source code, including navigating architecture, testing changes, and preparing pull requests.
Summary generated from the skill's SKILL.md.
About the developing-openrig skill
Navigating the OpenRig source code and preparing contributions is what this skill enables for developers working within a repository clone. It serves as a guide for identifying which packages or files own specific behaviors, determining if a command already exists via rig --help, and checking for planned features in ROADMAP.md. An agent should load this skill when a developer needs to understand the system architecture, assess the risk of a change using arteries.md, or prepare a pull request according to CONTRIBUTING.md.
This tool helps prevent common mistakes, such as attempting to restart the running daemon instead of using the repository's own test harnesses. It provides directions for running tests that utilize a private daemon and tmux server to avoid disturbing the active session. Developers use it to verify if a problem is already documented in the help reference or to find deep subsystem details within the as-built documentation. It focuses strictly on source code development rather than operating rigs or designing topologies.
What an agent can do with it
- 1Locate specific code ownershipFind which package or file is responsible for a particular behavior in the codebase.
- 2Assess architectural riskDetermine if a proposed code change affects high-risk areas like message delivery or migrations.
- 3Run isolated test suitesExecute tests using a private daemon and tmux server to avoid interfering with the current session.
- 4Prepare pull requestsFollow the established guidelines for opening a pull request and undergoing code review.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the developing-openrig skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the developing-openrig skill in Claude Code
~/.claude/skills/developing-openrig/SKILL.md
$ npx degit mvschwarz/openrig/.agents/skills/developing-openrig ~/.claude/skills/developing-openrigInstall the developing-openrig skill in Claude Code (project)
.claude/skills/developing-openrig/SKILL.md
$ npx degit mvschwarz/openrig/.agents/skills/developing-openrig .claude/skills/developing-openrigInstall the developing-openrig skill in Codex
~/.agents/skills/developing-openrig/SKILL.md
$ npx degit mvschwarz/openrig/.agents/skills/developing-openrig ~/.agents/skills/developing-openrigInstall the developing-openrig skill in Gemini CLI
~/.gemini/skills/developing-openrig/SKILL.md
$ npx degit mvschwarz/openrig/.agents/skills/developing-openrig ~/.gemini/skills/developing-openrigInstall the developing-openrig skill in Claude.ai
npx degit mvschwarz/openrig/.agents/skills/developing-openrig developing-openrig && zip -r developing-openrig.zip developing-openrig # claude.ai → Customize → Skills → + → Create skill → Upload a skill → developing-openrig.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablemvschwarz/openrig/.agents/skills/developing-openrig is public and reachablegithub.com/mvschwarz/openrig/tree/HEAD/.agents/skills/develo ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-12github.com/mvschwarz/openrig/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/mvschwarz/openrig/blob/HEAD/.agents/skills/develo ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/mvschwarz/openrig/blob/HEAD/.agents/skills/develo ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 76 linesgithub.com/mvschwarz/openrig/blob/HEAD/.agents/skills/develo ↗Pass
SKILL.md
View on GitHubDeveloping OpenRig
This skill is a map to the other maps. Each one is incomplete and may be stale: where a map and the code disagree, the code is right, and fixing the map is a welcome contribution.
First: which OpenRig are you in?
If you are an agent running inside OpenRig, two different OpenRigs are in play:
- The installed one runs your session.
rig --versionandrig daemon statusdescribe it. - The checkout is what you're changing.
git rev-parse HEADdescribes it.
Restarting the installed daemon does not run your checkout, and stopping it stops the agents running on it, including you. Test your change with the repo's own harnesses, which start a private daemon and tmux server (see "Test it" below), not by restarting the daemon you live in.
Find your way
| You want to know | Read | How much to trust it |
|---|---|---|
| What OpenRig can already do, before you decide something is missing | rig context get onboarding-width/public-what-you-can-do.md; in this checkout, packages/daemon/context-packs-src/onboarding-width/public-what-you-can-do.md (the installed copy can differ) |
The capability map; check it before proposing a new command or calling a gap a defect |
Whether a rig command already exists |
rig --help: the full command list, before you decide a command is missing |
The running binary; read the whole list, not only the command you expected |
| Whether a problem is already known | The "Known problems to compare against" section of docs/reference/help.md |
Lists known issues by symptom; check an issue's current status before relying on it |
| Whether a feature is already planned | ROADMAP.md |
Check it before proposing a feature |
| How the packages fit, the request path, where to add a command, route, migration, adapter, skill, context pack or scenario | ARCHITECTURE.md |
Checked against the commit it names; counts come with the command to refresh them |
| Whether your change touches a high-risk area, what depends on it, what broke there before | docs/as-built/arteries.md |
Incomplete by design: absence from it doesn't make a change safe |
| What to run before you push, and what each layer can and can't prove | docs/as-built/test-layers.md |
Checked against the commit it names |
The exact behaviour of a rig command |
rig <command> --help on the running binary, then packages/cli/src/commands/ |
The binary and the code win over any document |
| A subsystem in depth | docs/as-built/ |
Each module names the commit it was last checked against in last-verified-against-source; compare that marker with git log before relying on it |
| Rig spec, agent spec and other user-facing reference | docs/reference/ |
Ships to every user; if you find drift, fix it there |
| Which shipped skill covers a task | skills/_canonical/core/openrig-skills/SKILL.md |
The index of the skills that ship with OpenRig |
| How to open a good pull request, and what review looks like | CONTRIBUTING.md |
Current |
If none of these answers your question, search the code before inventing an answer. A missing map is worth an issue.
Before you change an artery
If your diff touches anything in arteries.md (message delivery, launch and resume, the queue, rig identity, skill
projection, process observation, migrations, restore):
- Read the artery row: what depends on it, and the past regressions listed there.
- Describe the downstream effect in your pull request, not just the diff.
- Add or extend a stub-agent scenario, or say precisely why the stub can't exercise it and what you ran instead.
Test it
The short version is npm run build, npm run lint, npm test. test-layers.md has the full ladder, including the
stub-agent scenarios, which run the real CLI, daemon, tmux and SQLite with scripted agents and no model cost.
- The scenario runner starts its own daemon and tmux server and drops your session's
TMUXand daemon variables, so it won't touch the daemon your session runs on. - A stub proves OpenRig's own plumbing, not how Claude Code or Codex behave. Say which you exercised.
How we judge changes
OpenRig is a coordination layer for a trusted environment: it should help agents and people keep work flowing.
- A change that removes friction, or makes state more truthful, is usually welcome.
- OpenRig runs on agents working in context with tools. Before adding code for a behaviour, ask whether an agent with
the right instructions and today's commands could do it. A skill or a page of guidance is often the better change.
- Where to look: the capability map above, and the
agent-operated-workflowsskill, which ships in theopenrig-coreplugin (packages/daemon/assets/plugins/openrig-core/skills/agent-operated-workflows/SKILL.md).
- Where to look: the capability map above, and the
- A change that adds a refusal, a prompt or a required step needs the concrete case in CONTRIBUTING.md: who is harmed, how, and what it costs everyone else.
- One concern per pull request. Keep the diff reviewable in one sitting.
When the map is wrong
Fix it in the same pull request, or open an issue. Update a document's last-verified-against-source marker only when
you have actually checked it against that commit.
Files in this skill
1developing-openrig skill questions
How do I install the developing-openrig skill in Claude Code?
Run npx degit mvschwarz/openrig/.agents/skills/developing-openrig ~/.claude/skills/developing-openrig. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the developing-openrig skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I test my changes without affecting my current session?
Use the repo's own test harnesses which start a private daemon and tmux server, rather than restarting the daemon you are currently running in.
How do I know if a command or feature already exists in OpenRig?
Check the running binary using 'rig --help' for commands, or consult the capability map and documentation for existing features.