Guide · Agent skill
How to use the Specification System agent skill (specification-system)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The specification-system skill is guidance for an AI agent that is writing or reviewing OpenRig specs: declarative files that describe a repeatable team of AI agents, their roles, workflows and operating modes. It is for developers and teams who want a multi-agent setup they can reuse or share instead of retyping startup prompts. After this guide you will know how to install the skill, how to ask for it in plain language, and what it will check for in your specs.
Specification Systemmvschwarz/openrig · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the specification-system ZIP from this page and unzip it so SKILL.md sits in a specification-system folder.
- 2Place it in a skills folder. Move the folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm OpenRig is installed. The guidance refers to OpenRig's spec formats and CLI, so have OpenRig available in the environment where you will work.
- 4Ask for a spec task in plain language. Describe the spec you want to write or review and name the file type, such as rig spec, agent spec or workflow spec.
- 5Review the output against the failure modes. Check that workflow and operating mode are declared, that no local paths are required, and that the spec is intended to be reused rather than treated as a one-off.
- 6Prove it runs. Validate the spec, install it to the spec library, instantiate it on a clean OpenRig environment, and confirm runtime realization, not just structural validation.
What does the specification-system skill make the agent do?
The skill tells the agent how to author and review OpenRig's spec family: rig specs, agent specs, workflow specs, startup and context fragments, operating-mode declarations, and the user spec library that stores them. Specs describe repeatable topology and behavior so the setup does not have to be re-explained in chat.
The skill steers the agent toward four habits. It makes specs portable across machines, declares workflow and operating mode as well as team structure, keeps reusable intent in the library instead of creating one-off files, and treats structural validation as insufficient without a real runtime check.
- Spec: declares topology, role or workflow shape (for example rig.yaml, agent.yaml, workflow.yaml).
- Bundle: spec(s) packaged for sharing. Handled by a different skill, rig-bundles-and-shareable-artifacts.
- Extension: runtime behavior added to a user workspace. Handled by extension-and-user-workspace.
Install the specification-system skill
Download the skill ZIP from this page and unzip it. The skill's main file is SKILL.md. Place the unzipped folder in one of two locations: ~/.claude/skills/ to make it available across your projects, or a project's .claude/skills/ folder to limit it to that project.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Know what you need before using it
The skill references OpenRig's spec formats and CLI commands (rig, spec, agent, bundle). It is guidance for OpenRig work, so OpenRig needs to be installed for the advice to apply. The skill also points to related OpenRig skills (openrig-architect, workflow-runtime, rig-bundles-and-shareable-artifacts). Those are referenced but not included in the file reviewed, so install them separately if you need them.
The skill runs no scripts and makes no network calls. It only shapes what the agent writes and checks.
Trigger the skill with natural requests
You do not need a special command. Describe the spec task in plain language and mention the kind of file you are working on. The skill's description covers rig specs, agent specs, workflow specs, startup or context fragments, operating-mode declarations and designing the user spec library.
Requests that fit the skill include authoring a new spec, reviewing an existing one, or checking whether a spec will work on another machine.
- Write a rig.yaml for a three-agent review team that I can reuse on another machine.
- Audit this agent.yaml for anything that depends on my local paths.
- Add an operating-mode declaration to this workflow spec so the team knows how to run it.
- Review this spec before I share it: will it run on a clean OpenRig environment?
Check specs for the four common failure modes
The skill names four failure modes it watches for. Ask the agent to check your spec against each one.
First, a spec may describe the topology but omit the workflow or operating mode needed to use it. Second, a shared spec may rely on local paths or hidden startup fragments and fail on another host. Third, agents may edit a spec as a one-off file rather than preserving its reusable intent. Fourth, validation may confirm the YAML shape without proving the topology can run.
The skill also separates validation from runtime realization. Its proof standard is to author the spec, validate it, install it into the spec library, instantiate it on a clean OpenRig environment, and show both structural validation and runtime realization.
- Does the spec declare workflow and operating mode, not just structure?
- Does it avoid local paths and hidden fragments?
- Was it validated structurally AND realized at runtime on a clean environment?
What people use it for
- Writing a reusable rig.yaml and agent.yaml for a team of AI agents you run repeatedly.
- Auditing an existing OpenRig spec for hidden local-path dependencies before sharing it with a colleague.
- Adding workflow and operating-mode declarations to a topology that currently only describes its structure.
- Deciding whether a one-off setup should stay a manual rig assembly or become a reusable spec in your library.
Frequently asked questions
How do I install the specification-system skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to use the specification-system skill?
You need OpenRig installed, because the skill refers to OpenRig's spec formats and CLI commands (rig, spec, agent, bundle). The related skills it mentions are not included in the file reviewed, so you would need to install them separately if you want them.
Is the specification-system skill free?
The source material for this page does not state pricing or licence terms for the skill beyond its licence, which is Apache-2.0. Check the repository's licence file for the terms that apply.
Does the skill run scripts or access the network?
No. The skill runs no scripts and does not use the network. It is guidance that shapes what the agent writes and reviews.
When should I not use this skill?
Skip it for one-off rig setups you will not reuse, since the skill says manual assembly is fine for that. Also skip it if you are not running OpenRig, and use rig-bundles-and-shareable-artifacts instead when you want to package a finished topology for sharing.
Why does the skill say validation is not enough?
Structural validation only proves the YAML has the right shape. The skill says the real proof is runtime realization, meaning the declared topology actually runs on a clean OpenRig environment.
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 are building or sharing OpenRig rig and agent configurations, want reusable multi-agent setups, or need to audit a spec for portability before sharing it. Pick something else if your setup is one-off, you are not running OpenRig, or you only need to package a finished topology, which belongs to the rig-bundles skill.
Download the skill