Download packages/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does forming-an-openrig-mental-model live?
The publisher keeps it at https://github.com/mvschwarz/openrig.
Which agents can use forming-an-openrig-mental-model?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.
>-
name: forming-an-openrig-mental-model
description: >-
Use when the system around you does not make sense yet: you just booted into a seat and do not
know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not
certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do
not know how skills reach you or where context comes from; or you are about to act on a guess
about how OpenRig works. Gives the runtime mental model fast, so you stop guessing.
metadata:
cli_surfaces_referenced:
- ask
- capture
- down
- ps
- send
- transcript
- up
- whoami
openrig:
stage: factory-approved
sibling_skills:
- openrig-user
- openrig-architect
- openrig-upgrade
- agent-operated-workflows
- agent-operated-software
Forming an OpenRig Mental Model
You're new to OpenRig — or returning after time away — and you need to
quickly understand what kind of system this is, what your seat is, and what
the moves are. This skill is the fast on-ramp.
For depth, read the canonical reference docs the skill points to. This
skill's job is to get you oriented — accurate enough to operate, fast
enough to be useful — not to replace the canonical docs.
The 60-second mental model
OpenRig is a local control plane for multi-agent coding topologies. You
declare a topology of agents in YAML, boot it with one command, and OpenRig
manages tmux sessions, harness lifecycles, transcripts, snapshots, and
restoration. When the system goes down, OpenRig snapshots; when it comes
back, agents resume their conversations.
The product loop:
down (auto-snapshot) → up <rig-name> (auto-restore) → work → repeat
The unit of work is the rig — a topology of agents working together as
a single system.
The four-layer model (where you live)
Everything in agent engineering happens at one of four layers. OpenRig
operates at Layer 3.
Layer
Name
Analogy
What it is
L0
Model
CPU
Foundation model — Claude, GPT, Gemini. Stateless tokens-in/tokens-out.
L1
Agent Core
Process loop
The reason-and-act cycle: observe, plan, choose, act, repeat.
L2
Harness
Container / OS
Tools, memory, lifecycle around the model. Examples: Claude Code, Codex CLI.
L3
Rig
Docker Compose / Terraform
Multi-agent topology — what agents exist, how they relate. OpenRig.
You are an agent at L1 inside an L2 harness, configured by L3 OpenRig.
OpenRig manages your harness; the harness wraps the model; the model
generates your tokens.
Three pillars of context
OpenRig is built on three context-engineering pillars. When you're oriented,
you should know which pillar you're operating in:
Pillar
What it is
Where it lives
Ontology
What exists. Curated knowledge — facts, code maps, as-built docs.
Shipped public context packs plus project-authored docs; discover with rig context list.
Epistemology
Why an agent believes what it believes — reasoning, instincts, decisions.
Transcripts (auto-captured). Session logs. ADRs.
Topology
How agents are connected — pods, edges, communication paths.
OpenRig itself. RigSpec YAML.
OpenRig manages topology and exposes public context through rig context.
Project-authored sources supply project-specific knowledge; transcripts retain
recorded work. These sources already coexist. Discover the configured library
and selected task context rather than assuming a particular private corpus:
rig context list shows the configured packs, and rig context work-install
lists what the current project declares (intent, context files, skills), so you
read only the pieces a task needs.
The core vocabulary (read these terms literally)
Term
What it means
Rig
A topology of agents working together as a single system. Defined in YAML (RigSpec). The top-level object.
Pod
A bounded context group within a rig. Members of a pod share a context domain and continuity responsibility. Think Kubernetes pod for knowledge.
Member / Node
A single agent (or terminal-node service) within a pod.
Edge
A relationship between members or pods. Kinds: delegates_to, spawned_by, can_observe, collaborates_with, escalates_to.
Topology
The shape of the rig — how agents are grouped into pods, how edges connect them, how the whole thing fits together.
The topology YAML. Defines pods, members, edges, culture. File: rig.yaml.
RigBundle
A portable archive of a RigSpec + vendored AgentSpecs. Move topologies across machines.
Agent Starter
A named, reusable starting context bundle. RigSpec member can declare starter_ref.
Skill
A markdown file with frontmatter that an agent loads at boot or on activation. Cross-runtime standard at agentskills.io.
Profile
A named configuration within an AgentSpec. The rig spec's member field selects which profile to use.
Culture
Rig-wide constitution — how the team communicates, what "done" means, escalation rules. File: CULTURE.md.
Snapshot
Point-in-time capture of a rig — sessions, conversations, state. Restorable.
Session name
{pod}-{member}@{rig}. The canonical address for tmux sessions and agent-to-agent messaging.
The session-name format {pod}-{member}@{rig} is your address. When you
run rig whoami --json, you get back your full topology context: rig name,
pod, member, peers, edges, transcript path. On a large rig the peer list can be
a bounded, edge-first selection: peersNote then says how many are not shown,
and rig whoami --json --all-peers lists them all.
Rig classes (what kind of rig am I in?)
OpenRig has five rig classes. The class determines authoring discipline,
supervision, and lifecycle policy.
Class
Purpose
Lifecycle
kernel
Host-level supervision, intake, authoring. One per host.
Always on; never auto-hibernated.
project
Long-lived team bound to a codebase.
Stays hot when active; hibernates on explicit request.
Subclass of ephemeral whose output becomes permanent infrastructure.
Retired only after output verified in place.
managed-app
Services-backed rig with specialist agents (e.g., a vault specialist, a skill librarian).
Long-lived; accessed by other rigs.
You're probably in a project rig or managed-app rig if you're doing
substantive work. Knowing your class helps you understand the supervisory
expectations on your seat.
How skills load (the most important thing to get right)
Skills are an established cross-runtime standard at
https://agentskills.io/specification. Both Claude Code and Codex build on it.
The shape
A skill is a directory containing SKILL.md (uppercase). The SKILL.md has
YAML frontmatter (name, description) and a Markdown body. Optional
sibling directories: references/, scripts/, assets/.
Progressive disclosure (why skills scale)
The harness reads frontmatter cheaply at boot — names + descriptions of all
available skills. Body content loads only when a skill activates. This is
ambient awareness — you know all the skills exist; you only pay token
cost when you reach for one.
Where skills come from in OpenRig
Per-agent loadout: your AgentSpec's profile.uses.skills: [...]
determines what skills get projected into your runtime skill folder
(.claude/skills/ or .agents/skills/) before your harness boots. This
is the structural composition layer.
Cross-pod sharing: AgentSpecs can imports: [shared] to access a
shared skill pool. Built-in agents commonly do this.
Belt-and-suspenders: the spec projects skill files; startup guidance
also tells you to load specific skills. Both paths matter — if the
projection silently fails, the guidance still tells you what to read.
Where the harness actually loads from. Populated by rig up.
~/.claude/skills/, ~/.agents/skills/
User-level harness skill directories. Inspect the current projection and harness configuration to determine which skills are installed and where they came from.
Product skills that ship with OpenRig — the spec pool + the bundled plugin assets (openrig-user, openrig-architect, forming-an-openrig-mental-model, queue-handoff, claude-compaction-restore, …).
the skills authoring workspace
Skill authoring source (not runtime-loaded).
The product already discovers its installed shared skill pool and serves
packaged context through rig context list/get. Discovery and retrieval do
not prove that every skill was projected into every harness. Inspect the
selected profile and actual runtime directories; do not assume a universal
home/bootstrap installation from this table.
The product loop (your day-to-day)
rig up <rig-name> # boot or restore the topology
rig ps --nodes # see what's running
rig whoami --json # know who you are
rig send <session> "msg" # talk to a peer
rig capture <session> # see a peer's terminal
rig transcript <session> # read a peer's history
rig down <rigId> # snapshot and stop every agent; check rig ps first, only when asked
rig up <rig-name> # restore from snapshot
The first command in any new seat is rig whoami --json. It tells you your
rig, pod, member, peers, edges, and transcript path. Treat it as ground
truth — your CLAUDE.md or AGENTS.md startup overlay can be wrong; whoami
is authoritative.
Cultural posture (how to behave)
OpenRig has a few load-bearing cultural principles. Internalize these:
Honesty over convenience. If resume fails, say so loudly. Don't
silently launch fresh.
The agent is the power user. The CLI is designed for a 10x staff
engineer at the terminal. You're that user.
CLI is context engineering. Every error message and help text gives
you information to act on. Read errors carefully.
Convention over invention. Follow docker/git/kubectl patterns. Agent
muscle memory is real.
Semi-deterministic is OK. Core contracts are solid; edge cases are
agent-handled.
Pets, not cattle (today). OpenRig is currently optimized for long-lived
agents that develop instincts over sessions. Cattle support is on the
roadmap.
What you should do in your first 10 minutes
If you're booting into a new seat in an OpenRig rig:
rig whoami --json — recover identity. Know your rig, pod, member,
peers (--all-peers when peersNote says some are not shown).
Read your role guidance — typically delivered via startup files.
guidance/role.md for your specific seat.
Read the rig's CULTURE.md if it has one — the team operating
manual.
Check what skills you have — list .claude/skills/ or
.agents/skills/ in your cwd. Each skill has a frontmatter description
that tells you when to reach for it.
Check your peers — rig capture <peer-session> to see what they're
doing.
Check the transcripts if you're returning to an in-flight workstream
— rig transcript <session> --tail 100 for recent context.
Ask rig ask <rig> "<question>" if you need cross-cutting evidence
from the rig's transcripts and chat.
You're now oriented enough to start doing useful work.
Permission policy (at setup): OpenRig sets only a minimal usability floor on your harness permissions, then offers recommended policies you opt into (Locked / Standard / Open — or YOLO to bypass). If you're creating or bringing up a rig, that's a choice you make, not something OpenRig decides for you — see openrig-user's "Permission policy — pick one at setup" and the applying-a-permission-policy skill.
Going deeper (canonical references)
For real depth, these are the load-bearing canonical docs:
Reference
What it covers
docs/as-built/README.md (source checkout)
As-built map of territory — daemon architecture, system overview, package boundaries; routes to architecture and UI modules via codemap.md
rig --help, then rig <command> --help
The installed CLI surface, subcommands and flags
rig context get reference/rig-spec.md
The RigSpec YAML format — pods, members, edges, all fields
docs/reference/agent-spec.md (source checkout)
The AgentSpec YAML format — resources, profiles, imports
Placement and operating-model guidance — topology and work trees, context altitude
openrig-architect skill
Rig and topology authoring
https://agentskills.io/specification
The cross-runtime skill standard
If you're going to be authoring rigs, use the openrig-architect skill before
touching YAML.
What this skill is NOT for
Compaction recovery. That's claude-compaction-restore. Different
skill, different scenario.
Operating a specific rig. Specific rigs have their own DESIGN.md and
CULTURE.md. Read those.
Authoring a new rig. Use the openrig-architect skill for that.
Day-to-day OpenRig operation. Use openrig-user for that.
This skill exists to form your initial mental model of OpenRig as a
system. Once oriented, reach for the role-specific or task-specific skills
that fit your actual work.
Common misorientations to avoid
Misorientation
Reality
"OpenRig is a chat interface or assistant"
No. OpenRig is a control plane that manages your harness sessions. The chat happens inside the harness; OpenRig is around it.
"Pods are workflow groups"
No. Pods are context domains — agents that share working context. If two agents communicate every turn, they should be in one pod; if they communicate rarely, they shouldn't be.
"Edges represent reporting hierarchy"
No. Edges describe coordination shape — who delegates to whom, who observes whom. Avoid hierarchy interpretations; they distort behavior.
"I should manage Codex's compaction the way I manage Claude's"
No. Codex auto-compacts cleanly; Claude doesn't. Different runtimes, different lifecycles.
"MEMORY.md auto-loads, so I don't need to read it"
Maybe. Sometimes MEMORY.md auto-loads via system reminders; sometimes not. Don't assume. If your work touches the topics it covers, read it explicitly.
"Skills inherit from a parent or compose like classes"
No. Skills are flat artifacts; composition happens via AgentSpec profile.uses.skills (structural) or soft cross-references in skill bodies (advisory). Not via OO-style inheritance.
"The substrate shared-docs/skills/ folder is the canonical runtime path"
No. The harness doesn't read there. It's an authoring workspace. Runtime loads from .claude/skills/, .agents/skills/, and product built-in.
Disaster-recovery test for this skill
If you read only this skill, can you:
State what kind of system OpenRig is, in one sentence?
Name the four layers and where you live?
Run rig whoami --json and interpret the output?
Find your role guidance and your peers?
Identify what kind of rig you're in (kernel / project / ephemeral / etc.)?
Know where to look for a skill body (which folder)?
Know what to read next for depth (the canonical references)?
If yes — you're oriented. If no — tell your peer or the human; missing
context is fixable, but only if surfaced.
How do I install forming-an-openrig-mental-model?
Download packages/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does forming-an-openrig-mental-model live?
The publisher keeps it at https://github.com/mvschwarz/openrig.
Which agents can use forming-an-openrig-mental-model?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.