Guide · Agent skill
How to use the OpenRig Operating Model agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The openrig-operating-model skill teaches an AI agent where a lesson, note, document or convention should live inside an OpenRig multi-agent setup, and how to find that context again later by reading one consistently named file at each folder level. This guide is for people who may never have used agent skills before, and it walks through what the skill does, how to install it, how to trigger it, what it needs and what to watch for. After reading it you should be able to install the skill, ask an agent to use it for a placement question, and decide whether it fits your setup.
OpenRig Operating Modelmvschwarz/openrig · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from the directory page and unzip it so that SKILL.md sits inside the skill folder.
- 2Choose the install location. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ for one project. Or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check the requirements. Confirm bash and python3 are available and that you have a local OpenRig topology directory structure if you plan to use compose.py.
- 4Ask a placement question. Describe where a lesson, note or document should go, in plain language, so the agent's description match triggers the skill.
- 5Follow the trace. Let the agent read the one filename at each level from its position up to the fleet, rather than guessing or creating new names.
- 6Scaffold new files carefully. Use the templates and scaffold.sh for missing files, reviewing what will be written first since existing files are not overwritten but new ones are created.
What is an agent skill and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md instruction file, plus optional templates and scripts, that an AI agent can load when a task matches the skill's description. This one is about structure rather than code: it gives the agent a model for organising context in an OpenRig topology.
The core idea is a trace. Context lives on two trees: a topology tree (fleet, instance, rig, pod, seat) describing how work is done, and a work tree (project, mission, slice, proof item) describing how the product gets built. Every kind of context is a chain, meaning the same filename appears at every level. To learn something, the agent reads that filename from its own position up toward the root, and nearer levels refine or override farther ones.
The skill also enforces a few rules. The trace follows directory paths only, with no pointer fields or link-following. A file keeps one name across all levels, so a seat's LEARNED.md is different from a rig's LEARNED.md because the folder path identifies it. Knowledge that already has a home should not be duplicated.
Install the openrig-operating-model skill
Download the skill ZIP from the directory page and unzip it. You have two main options. For a personal setup, unzip it into ~/.claude/skills/ so the skill is available across your projects. For a single project, unzip it into that project's .claude/skills/ folder so it applies only there.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
After installing, the skill folder should contain SKILL.md, a templates/ folder and a scripts/ folder. If the SKILL.md file is not directly inside the skill folder, the agent will not find the instructions.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with natural requests?
You do not need a special command. The skill's description tells the agent when to use it: when it does not know where something belongs, is about to create a new doc, folder or convention, is deciding whether something should be a skill, a note or a chain file, has inherited a seat, or is about to duplicate knowledge that already has a home. Ask in those terms and the agent should load it.
Plain requests work well. Name the situation and the question, and mention OpenRig if relevant.
- "I learned that this seat must check the queue before handover. Which file should that go in?"
- "I am about to create a new architecture doc for this rig. Does something already cover it?"
- "I just inherited the pm-lead seat. What should exist for it?"
- "Should this be a skill, a note or a chain file?"
What do you need before you use it?
The source lists bash and python3 as requirements. The python3 requirement is for scripts/compose.py, which uses only the standard library. The skill also expects access to a local OpenRig topology directory structure. It refers to an 'ar' module imported by compose.py, but that module is not included in the files, so the Python composition script may not run on its own.
Network access is not used. Because the scaffold scripts write files into folders, the skill is only practical where agents are allowed to create or edit files in your repository.
- bash
- python3 (for scripts/compose.py, standard library only)
- A local OpenRig topology directory structure
- Runs scripts: yes. Uses network: no.
What the bundled templates and scripts do
The skill ships starter templates: LEARNED.md (what a specific seat or node has learned), SOP.md (how a kind of seat or pod works), SPEC.md (a work node's intent and specification), NOTES.md (the working record of a piece of work) and PLAYBOOK.md, which is a legacy pointer to SOP.md.
The scripts are small helpers. scaffold.sh creates missing files without overwriting existing ones. trace-due.sh and trace-stamp.sh deal with whether a trace is due and record that one was done. trunk-diff.sh and compose.py are also included. Read each script before running it, especially since scaffold scripts write into folders.
- templates/LEARNED.md, SOP.md, SPEC.md, NOTES.md, PLAYBOOK.md
- scripts/scaffold.sh creates missing files without overwriting existing ones
- scripts/trace-due.sh checks whether a trace is due
- scripts/trace-stamp.sh records a trace
- scripts/trunk-diff.sh and scripts/compose.py are also included
Example: placing a lesson
Suppose a seat learns that handovers fail unless it lists its standing duties. The agent, following the skill, asks which level the lesson concerns. A lesson about how one seat works belongs in that seat's LEARNED.md, since the seat's own file is the one that fixes handovers. A lesson true of every rig on a daemon belongs in the instance-level LEARNED.md. Work-specific observations go to the NOTES.md of the mission or slice where the work happened.
Ask the agent to explain its choice. The reasoning should name the level and the file, and it should avoid writing the same lesson in two places.
What people use it for
- Deciding whether a newly learned seat-specific procedure belongs in LEARNED.md, SOP.md or a skill
- Orienting an agent that has just taken over a seat by listing what should exist at each level
- Keeping a multi-agent OpenRig setup from duplicating the same convention across rigs and pods
- Creating consistent starter LEARNED.md, SPEC.md and NOTES.md files for new seats or work nodes
- Writing a path-based context convention of your own, using this skill as a worked example
Frequently asked questions
Is the openrig-operating-model skill free to use?
The source lists the licence as Apache-2.0. Check the licence file in the package for the full terms before you redistribute or modify it.
Do I need OpenRig to use this skill?
Practically, yes. The skill references OpenRig's topology and work trees, and it refers to library addresses and plugins that may not exist in your environment. Without OpenRig the concepts add little value.
Where do I install the skill in Claude?
Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.
What do I need to run the scripts?
You need bash and python3. The compose.py script uses only the Python standard library, but it imports an 'ar' module that is not included in the files, so it may not run without that module.
Does the skill use the network?
No. The source states that the skill does not use the network. It does run scripts, and the scaffold scripts write files into folders, so review them before running.
How is this different from just keeping a notes file?
Instead of one notes file, the skill gives a structure: the same filename at each level of a folder tree, a rule that the path is the only way to find context, and templates that separate lived notes from authored procedures.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you run or build multi-agent OpenRig topologies with many seats, rigs and pods, or if you keep agent memory and specs as Markdown and want consistent placement rules. Skip it if you use agents in a single chat, cannot let agents write files in your repository, or do not run OpenRig, since the model depends on that structure.
Download the skill