How to use the Minion Orchestrator agent skill

What the skill makes the agent do

Without this skill, an agent usually runs work directly in the session. If the session ends or the process dies, the work can be lost. The Minion Orchestrator skill tells the agent to submit durable work to the Minions queue instead. Jobs in that queue survive gateway restarts, and the agent can check on them, pause, resume, cancel or redirect them while they run.

The skill covers two kinds of job. Deterministic shell jobs run a command or script with no LLM reasoning loop, for example ETL steps or cron work. LLM subagent jobs run an agent on research or iterative tasks, and can fan out into several parallel streams.

• Jobs survive gateway restart because they are stored in Postgres.
• Every job reports structured progress and token accounting, and keeps session transcripts.
• Running agents can be steered mid-flight with inbox messages.
• Jobs can be paused, resumed or cancelled.
• The skill also carries rules for confirming that a long result actually reached the user.

Install the skill (ZIP or Claude apps upload)

The skill is distributed as a ZIP from this page. The package contains a single file, SKILL.md. Unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill limited to one project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• 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

Set up the gbrain tooling the skill needs

The skill only works with the gbrain CLI and project (garrytan/gbrain) and a Postgres database, or PGLite for inline runs. Without that tooling the skill has nothing to submit jobs to. For shell jobs, a worker must be running with shell jobs explicitly allowed. The source describes two ways to do this: a flag on the command, or an environment variable on the worker.

Shell jobs are blocked by default. A worker started without the flag marks a shell job as dead immediately, and the error names the missing flag. A job that stays in waiting means no worker is running at all. After configuring, run the stats command to confirm the worker is consuming the queue.

• Start the worker with: gbrain jobs work --allow-shell-jobs
• Or export GBRAIN_ALLOW_SHELL_JOBS=1 on the worker. A .env file in the worker's directory cannot set it.
• Check the queue with: gbrain jobs stats
• Check worker supervision with: gbrain jobs supervisor status if jobs sit in waiting

Trigger the skill with natural requests

You do not need to name the skill. The agent matches requests such as running something in the background, checking on an agent, or doing several tasks in parallel. The skill's trigger phrases include: submit a shell job, run in background, spawn agent, check on agent, what's running, steer agent, pause agent, resume agent, parallel tasks, fan out, long operation and durable execution.

If a request is unclear, the skill asks one question: whether you want a deterministic shell command job or an LLM agent job.

• "Run this ETL script in the background and tell me when it finishes."
• "What's running right now?"
• "Check on the research agent and tell me its progress."
• "Do these three research tasks in parallel."
• "Pause the indexing agent and resume it after the restart."

Submit and monitor shell jobs

Shell jobs take their command as a JSON object passed to --params. The object has a cmd string or an argv array, plus cwd and optionally env. An operator or autopilot submits the job from the command line. The agent then monitors it. For a job that should finish in one go on PGLite, add --follow to run it inline.

Agents can observe shell jobs with list_jobs, get_job and get_job_progress, but cannot submit them over MCP. Submitting a shell job over MCP fails with a permission_denied error.

• Command string form uses cmd, for example echo hello with an absolute cwd.
• Argv form runs without shell expansion.
• Other submit flags listed by --help include --queue, --priority, --delay, --max-attempts, --timeout-ms, --idempotency-key and --dry-run.
• Monitor with list_jobs --name shell --status active, then get_job ID for exit code, stdout and stderr tails.

Choose between a shell job, a subagent, or inline work

The skill routes requests using a table. A plain command or script goes to a shell job. A request for research or reasoning goes to a subagent job. A single operation under about 30 seconds should usually run inline, because it is simpler. Anything expected to run longer than about two minutes goes through the durable execution steps, and parallel work of two or more streams uses a fan-out manifest or parent and child subagents.

Routing is governed by a project convention. The default is pain-triggered: native subagents are used first, and Minions are used once a specific problem appears. Routing through Minions for everything is opt-in.

• Deterministic command: shell job
• Research or iterative agent work: subagent job via gbrain agent run
• Under about 30 seconds: inline first
• Over about 2 minutes: durable execution ladder
• Two or more parallel streams: fan-out

Confirm results reached you

The skill asks the agent to verify delivery, not just process exit. A swallowed completion message looks the same as a dead job from your side. A deadman check is a scheduled follow-up that confirms the result was reported to you. It is backup insurance, not a guarantee: the check can itself fail, so on the next turn the agent sweeps active and recent completed jobs for overdue results. Checkpoints are only trusted when their timestamps are fresh, since a stale checkpoint looks like a job still running.

• Deadman checks are idempotent and check reported state first.
• Recovery reports carry the job ID so duplicates can be spotted.
• Compare checkpoint timestamps with gbrain jobs get ID.