How to use the Forming an OpenRig Mental Model agent skill

What is an agent skill?

A skill is a folder containing a file named SKILL.md. The file has a short header (YAML frontmatter with a name and description) followed by Markdown instructions. Agent runtimes such as Claude Code and Codex read the name and description of each available skill at startup, and load the full body only when a skill is activated. That keeps the agent aware of many skills without paying the context cost of all of them at once.

Skills follow a cross-runtime standard published at agentskills.io/specification.

What this skill makes the agent do

When the agent is unsure how the system around it works, this skill gives it a condensed runtime model. It explains that OpenRig is a local control plane for multi-agent coding setups: a rig is defined in YAML, booted with one command, and OpenRig manages tmux sessions, transcripts, snapshots and restoration. It also defines core vocabulary (rig, pod, member, edge, topology, profile, culture, snapshot and session name) and the five rig classes.

The skill is an on-ramp, not a replacement. It points to the official reference docs for depth. The visible SKILL.md is descriptive text only; it does not change files or run commands on its own.

• Explains the product loop: down (auto-snapshot), then up <rig-name> (auto-restore), then work.
• Maps OpenRig to a four-layer model: model, agent core, harness and rig.
• Explains the three context pillars (ontology, epistemology and topology) and where each lives.
• Explains how skills load and where a seat's skills come from.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The unzipped folder should contain SKILL.md. Then place the folder in one of two locations, depending on how you want to use it.

For a personal setup, put it in ~/.claude/skills/. For a single project, put it in the project's .claude/skills/ folder so it is available only there.

You can also upload the ZIP through the Claude apps: open Settings, go to Capabilities, then Skills, and add the skill there.

• Personal install: ~/.claude/skills/ (folder with SKILL.md inside).
• Project install: .claude/skills/ inside your project.
• Claude apps: Settings, then Capabilities, then Skills, then upload.

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to use it, so ask in plain language when the system feels unclear. The description covers situations such as having just booted into a seat, hearing a term like rig, pod, seat, fleet, topology or slice without knowing what it means here, or being about to act on a guess about how OpenRig works.

Requests that tend to match the skill include the examples below.

• Explain how the pieces of this rig fit together before we change anything.
• What is a pod here, and how is it different from a seat?
• I just booted into this seat. What kind of rig am I in and what is it for?
• Where does my context come from, and how do my skills reach me?

Use the CLI commands the skill points to

The skill references OpenRig CLI commands. Your agent can use them to check its real situation rather than rely on memory. The skill names rig whoami, which returns your topology context (rig name, pod, member, peers, edges and transcript path). With compact output enabled on a large rig, the peer list may be a bounded selection, and rig whoami --json --all-peers lists them all.

To see what context is available, the skill points to rig context list, which shows configured context packs, and rig context work-install, which lists what the current project declares (intent, context files and skills).

• Session names follow the format {pod}-{member}@{rig}; this is your address for messaging.
• Read only the context pieces a task needs.

Check what it needs and how it behaves

The skill needs an existing OpenRig installation, because it describes that system's CLI and files. The skill itself runs no scripts and makes no network requests. Its files are plain Markdown, so nothing in it executes when you install or activate it.

Because it only explains concepts, do not expect it to edit your project or run commands for you. Use the sibling skills for operational work: openrig-user for running and operating OpenRig, and openrig-architect, openrig-upgrade, agent-operated-workflows and agent-operated-software for related tasks.

• Requires: an OpenRig installation.
• Runs scripts: no.
• Uses network: no.
• Not for installing or running OpenRig itself; use openrig-user for that.