How to use the OpenRig Architect agent skill

What is an agent skill?

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. The skill's main file is SKILL.md, which tells the agent when to use it and how to work through a task.

The openrig-architect skill ships as a single SKILL.md file. It is mostly a detailed procedure and reference guide: it tells the agent which OpenRig reference docs and commands to consult and in what order.

What the skill makes the agent do

When the skill is active, the agent acts as an architect for OpenRig. Given a goal, it works out who is needed, how the agents are grouped into pods (bounded groups that share a workflow concern), what role each member plays, and what guidance, skills and startup content each one receives.

It then writes the topology file (RigSpec) and the agent specification files (AgentSpec), checks them with validation commands, and helps diagnose a launched rig whose agents are not behaving as intended.

• Plans pods and members from the user's intent
• Writes RigSpec and AgentSpec files for a new rig
• Creates agent startup content: guidance, skills and culture
• Validates specs and diagnoses misbehaving agents in a launched rig

Install the skill

Download the ZIP from the directory page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements first

The skill depends on OpenRig itself. It expects OpenRig to be installed with its rig CLI and daemon, and it needs access to the OpenRig reference docs, either at ~/.openrig/reference/ (a default location, not a fixed one) or in the OpenRig source repository. The agents your rig launches need a runtime such as Claude Code or Codex.

Without OpenRig installed, the skill has nothing to work with. It does not change OpenRig itself and it is not a general tutorial on multi-agent systems.

• OpenRig installed, with the rig CLI and daemon
• Reference docs at ~/.openrig/reference/ or in the source repository
• A runtime such as Claude Code or Codex for the launched agents

Trigger the skill with natural requests

You do not need a special command. Describe the outcome you want in plain language and mention the rig or team. The skill's description covers three kinds of request: designing a new topology, authoring specs and startup content, and diagnosing a launched rig.

The skill is meant to be used with other OpenRig skills. Changing OpenRig's source belongs to developing-openrig, and routine day-to-day operation of an existing rig belongs to openrig-user.

• Design: "I need a team that builds and tests a small web app. Help me plan the rig."
• Author: "Write the RigSpec and agent specs for a three-agent monitoring rig."
• Diagnose: "My reviewer agent in the running rig keeps skipping its checks. Why?"
• Out of scope: "Change how the OpenRig daemon handles startup." (use developing-openrig)

Example: designing a rig from a goal

Start with the outcome, not the agent count. The skill asks about the goal, the workflow and handoffs, the project and tech stack, which runtimes you have, and how autonomous the team should be. Answer what you know and let the agent ask about the rest.

The skill advises starting small. A three-agent rig (an orchestrator plus one or two working pods) is a good first target, because it lets you confirm the specs boot and work before you scale up. Agents do not all need to be busy at once; some can be available on demand.

• Pair (2 agents): one implements, one verifies
• Small team (3-5 agents): orchestrator plus one or two working pods
• Full team (6-10 agents): several bounded contexts, such as development, review and research

Safety notes: scripts and network

This skill runs no scripts and uses no network access, according to its description. It works by reading reference docs and running OpenRig's own CLI commands that the agent chooses to run in your environment.

Review what the agent proposes before it writes files or launches a rig. Check that any command it runs is one you expect, and that the specs match your project's rules.

• Runs scripts: no
• Uses network: no
• Reads local reference docs and runs OpenRig CLI commands in your environment

Tips for better results

Give the agent your real constraints: the codebase, the runtimes you have, and any team rules that apply. The skill tells the agent to read the actual project authority rather than assume it, so point it to your rules when you have them.

When a launched rig misbehaves, describe the symptom and what you expected. Keep the names of rigs, pods and members stable across runtime choices, since edges and workflow targets refer to those IDs.

• Name rigs by purpose, pods by domain, and members by role
• Ask for validation after each spec change
• Start with a small rig and expand once it works