Guide · Agent skill
How to use the Queue Handoff agent skill (queue-handoff)
Updated · written with AI from the project's own documentation and checked against our catalogue data
Queue Handoff is an agent skill for OpenRig, a multi-agent setup where several AI agents work in named seats. It teaches an agent to end a unit of work by passing it to a named next owner, another agent or a human, through a durable queue item instead of going idle or leaving the work stuck in chat. After this guide you will know how to install the skill, how to trigger it with plain requests, and how the default wake-up nudge and --no-nudge flag behave.
Queue Handoffmvschwarz/openrig · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP from the page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm the prerequisites. Make sure the OpenRig rig CLI with queue commands is available and the OpenRig daemon is running.
- 3Describe the handoff in plain words. When you finish a slice or get blocked, say so in your request, such as asking the agent to hand the next step to a named seat.
- 4Pick the right command. Use handoff-and-complete to pass finished work on, block to wait on another queue item, or park with --wake-after for work waiting outside the queue.
- 5Add a summary and keep the default nudge. Include --summary on every create, handoff and handoff-and-complete, and leave out --no-nudge unless you intend a cold park or human gate.
What the Queue Handoff skill makes the agent do
The skill covers the moments when an agent is finishing a slice, ending a turn, blocked on another agent's work, or escalating to a human. In each case the agent should hand the work to a named owner through a queue item, so the system keeps moving across context compactions, missed messages, and interruptions.
The skill calls this the hot-potato terminal-turn rule: active work ends by passing the ball, not by going idle. It also explains default-nudge semantics and when the --no-nudge flag is appropriate, such as an intentional cold park or a human gate.
- Hand off finished work to a named next owner instead of leaving it in chat.
- Park work that waits on something outside the queue, such as CI or a long job, with a timer.
- Escalate to the human as a durable attention item, not only a chat message.
- Close dispatches you opened when your own transition makes them moot.
Install the Queue Handoff skill
Download the skill ZIP from the page. Then choose one of two routes. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the ZIP there.
The package contains a single file, SKILL.md. The skill does not run scripts and does not use the network, so installing it only adds instructions for the agent to read.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check what you need before you start
The skill's commands assume the OpenRig rig CLI is installed and includes the queue commands. The OpenRig daemon must be running, because it enforces the queue state rules. Without these, the commands in the skill will not work.
If you are working alone in a chat with no queue and no other agents, this skill is not the right fit. It is also not suitable if your team uses a different queue system, since the rig queue commands and state machine will not apply.
- OpenRig rig CLI with queue commands
- OpenRig daemon running
- Multiple agents or a human owner to hand work to
Trigger the skill with natural requests
You do not need a special command to use the skill. Describe the situation and the agent should pick it up from the skill's description. The skill is relevant when an agent ends a turn, finishes a slice with a clear next step, gets blocked on another agent, or needs to escalate.
For a finished slice with a next step, the skill uses a create-and-handoff pattern. For a blocked item, it uses the block command. For work waiting on something outside the queue, it parks the row with a wake timer.
- "Finish this slice and hand the next step to the reviewer seat."
- "You're blocked on the database agent's migration. Park this under that item."
- "Waiting on CI for this build. Park it and wake me after 30 minutes."
- "Escalate this decision to me as an attention item."
rig queue block <id> --on external:<what> --wake-after <duration> --continuation "<what resumes>"Understand closure reasons and default nudges
Every queue item closes with a closure reason. The skill lists these: handed_off_to means work continues at a different seat, denied means the receiver rejected it, canceled means sender or receiver withdrew it, no-follow-on means terminal completion, escalation means it moved to a higher tier, and superseded means another queue item replaced it. handed_off_to and escalation also require a closure target.
Queue writes nudge the receiver by default. This applies to rig queue create, rig queue handoff, and rig queue handoff-and-complete. The only suppression flag is --no-nudge. Use it only for an intentional cold park, a human-gate signal, or a deliberate poll-driven workflow, not for live-loop handoffs where motion matters. The skill also says that a --notify flag does not exist, so an instruction that uses it is probably out of date.
- Leave out --no-nudge in a live loop and trust the default.
- Use handoff-and-complete to pass work on. It closes your row and records the successor in one step.
- A create followed by an update to done with handed_off_to records no successor, so the stuck sweep will raise a recovery item.
rig queue handoff-and-complete <id> --summary "<what it is and why this seat>"Follow the discipline: end with an edit or a send
A turn that ends with a self-instruction typed but never sent has not handed off. The seat sits idle until someone notices. The skill's rule is that your last act on a turn must be an edit, a send, or a queue handoff, never a drafted prompt line left in the buffer.
After handing off, pull your next item from your own queue rather than going idle with work still waiting. Go truly idle only when your queue is empty, then wait for the baton. When your own transition supersedes dispatches you sent earlier, close those dispatches yourself with a citation to the event that superseded them.
- Last action on a turn: an edit, a send, or a handoff.
- After a handoff, check your own queue and pull the next item.
- Run an outbox audit after each phase transition or fold receipt and close moot dispatches.
What people use it for
- An implementer finishes a code slice and hands the review step to a reviewer seat with a clear summary.
- A seat is blocked on another agent's migration and marks its queue item blocked on that child item until it completes.
- An agent waits on a long CI run, parks the item with a timer, and resumes automatically when the timer fires.
- An agent hits a decision only a person can make and escalates it as a durable attention item rather than a chat message.
Frequently asked questions
Is the Queue Handoff skill free and what is its licence?
The skill is listed under the Apache-2.0 licence. The source does not describe pricing, so check the repository and the page for any cost details.
What do I need to use the queue-handoff skill?
You need the OpenRig rig CLI with queue commands and the OpenRig daemon running, because the daemon enforces queue state rules. The skill assumes a multi-agent setup. It does not run scripts or use the network.
How do I install the queue-handoff skill?
Download the ZIP from the 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.
Why did my agent's queue handoff send a notification I did not want?
Queue writes nudge the receiver by default on create, handoff and handoff-and-complete. Add --no-nudge only for an intentional cold park, a human-gate signal, or a deliberate poll-driven workflow. In a live loop, leave it out.
Can I use this skill with a different queue or task system?
No. The skill's commands and state machine are specific to the rig queue commands in OpenRig. If your setup uses a different queue system, the skill will not apply.
Does the skill work for a single agent with no team?
Not well. It is built for handing work between seats or to a human. For a single-agent chat or a simple project with no queue, the commands do not fit.
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 multi-agent workflows on the OpenRig daemon and want agents to hand off work reliably, survive compactions and missed messages, and avoid stalled seats. Pick something else if you work alone, do not use OpenRig's rig CLI, or run a different queue system, because the commands and state rules here will not apply.
Download the skill