name: agent-orchestration-kit description: > Use when setting up or managing a multi-agent task orchestration system on OpenClaw. Use this skill whenever the user wants to: coordinate multiple agents, set up an agent team, dispatch tasks across agents, track task progress in real-time, add approval gates to agent workflows, create a star topology with a leader agent, build a multi-agent pipeline, manage agent callbacks, or anything involving agents working together on tasks. Also use when the user says "set up agents", "build a team", "orchestrate work", "multi-agent workflow", "agent coordination", or "task dispatch". version: 0.2.0 author: kuannnn metadata: { "openclaw": { "emoji": "🎛️", "requires": { "bins": ["node"] } } }

Agent Orchestration Kit

Overview

This skill sets up a multi-agent task orchestration system on OpenClaw. It creates:

• Star topology — Leader hub + specialist spokes, no spoke-to-spoke communication
• Fully async dispatch — sessions_send with timeoutSeconds: 0, Leader is never blocked
• Task file tracking — each task is a markdown file with full state, steps, outputs, and log
• Structured callback protocol — standardized signals drive Leader's routing decisions
• Real-time status notifications — owner sees live progress updates on every dispatched task
• Approval workflow — nothing executes externally without explicit owner approval
• Heartbeat safety net — automatic stale task detection and recovery every 3 minutes via OpenClaw Heartbeat

What This Kit Is

This is not a prompt pack or a collection of agent personas. It is an orchestration protocol — a set of rules that govern how multiple agents coordinate work:

1. Leader decomposes requests into atomic tasks
2. Each task becomes a file before dispatch — the single source of truth
3. Agents work asynchronously and callback with structured signals
4. Leader processes callbacks, updates status, and routes next steps
5. Quality gates and approval workflow prevent unreviewed output from reaching external systems

The agent roles are pluggable — swap in any specialist. The orchestration rules are the constant.

Prerequisites

1. OpenClaw v2026.2.26+ installed and openclaw onboard completed
2. At least one auth profile exists
3. ~/.openclaw/ directory exists

Onboarding Flow

When first triggered, this skill runs an interactive setup process.

Step 1: Prerequisites Check

• OpenClaw installed and openclaw onboard completed
• ~/.openclaw/ directory exists
• At least one auth profile configured

If any prerequisite is missing, guide the user to resolve it before continuing.

Step 2: Team Selection

Present team templates. All teams include Leader (required), Executor (recommended), and the Reviewer pattern (on-demand).

See templates/teams/ for team definitions. See templates/agents/ for all available agent templates.

After team selection, the user can add individual agents from the template catalog or create custom agents.

Step 3: Instance Configuration

Collect from the owner:

1. Name (optional) — How the team addresses the owner. Can be omitted if Leader's SOUL.md/USER.md defines identity.
2. Timezone — For scheduling and timestamps (e.g., Asia/Taipei, US/Pacific)
3. Communication language — Language for all owner-facing messages (agent-to-agent is English)

After collecting, write the values to shared/INSTANCE.md (created by scaffold). Also update Leader's SOUL.md communication section to reflect the chosen language.

Step 4: Run Scaffold

# Create directories, copy templates, inject orchestration rules
bash scripts/scaffold.sh \
  --skill-dir "$(pwd)" \
  --team \x3Cselected-team>

# For named leader workspaces:
# bash scripts/scaffold.sh --skill-dir "$(pwd)" --team \x3Cselected-team> --leader-workspace workspace-bae

The scaffold creates:

• Agent workspace directories with SOUL.md and AGENTS.md
• Orchestration protocol rules injected into every agent's AGENTS.md
• Shared operations files (shared/operations/)
• Task tracking directory (tasks/, tasks/archive/)
• Heartbeat template (HEARTBEAT.md) for task status checking

Step 4b: Preview & Merge Config

Always preview before merging. Run dry-run first so the user can inspect what will change:

# Preview what will be merged (no changes written)
node scripts/patch-config.js \
  --config ~/.openclaw/openclaw.json \
  --dry-run

Show the user the dry-run output and explain what each section does. Only proceed after confirmation:

# Apply the merge
node scripts/patch-config.js \
  --config ~/.openclaw/openclaw.json

What the config patcher merges:

Version compatibility: The script checks for OpenClaw v2026.2.26+ features (A2A sessions, agent list, exec trusted dirs). If the version is older, it will warn and suggest upgrading.

Safety: The script creates a timestamped backup of openclaw.json before writing. Restore with: cp ~/.openclaw/openclaw.json.backup-\x3Ctimestamp> ~/.openclaw/openclaw.json

Step 5: Verification

openclaw gateway restart
openclaw doctor

Verify:

• Leader responds to messages
• sessions_send to at least one agent succeeds
• HEARTBEAT.md exists in the leader workspace
• After 3+ minutes, leader session shows heartbeat activity (check session logs)

The orchestration kit uses OpenClaw's Heartbeat mechanism (configured automatically by patch-config.js at 3-minute intervals). Task status messages and results are sent to the channel where the owner's request originated (the task's route). There is no fixed operations channel for routine updates.

If heartbeat is not triggering, ensure agents.defaults.heartbeat is set in openclaw.json AND the leader agent entry has an explicit heartbeat block.

Agent Structure

Required: Leader

The orchestration hub. Cannot be removed.

• Task analysis and decomposition
• Agent routing and async dispatch
• Callback processing and quality review
• Status notification management (send on dispatch, edit on every callback)
• Approval workflow gating
• Owner communication (only agent with direct owner access)

Full protocol: templates/leader/AGENTS.md Persona: templates/leader/SOUL.md

Recommended: Executor

Prevents Leader from blocking on heavy operations.

• File operations, CLI, configuration changes
• Workspace maintenance, directory operations
• Any operation that could take >30 seconds

Leader has exec access as fallback, but the protocol guides it to delegate time-consuming operations to Executor.

Template: templates/executor/

Built-in Pattern: Reviewer

Not a persistent agent. Spawned on-demand via sessions_spawn when:

• High-stakes deliverables need independent review
• Owner explicitly requests review
• Two consecutive rework failures on the same task

Uses [APPROVE] / [REVISE] signals. Max 2 review rounds per task.

Template: templates/reviewer/

Specialist Slots

Filled from templates or custom definitions. Each specialist receives:

1. Role-specific content from the chosen template (persona, workflow, output format)
2. Orchestration rules auto-injected by the scaffold (callback format, signals, context loss recovery)

Available templates:

See templates/agents/_template.md for the blank template structure.

Core Protocol — Quick Reference

Task Lifecycle

Owner request → Leader analyzes → Decomposes into atomic tasks →
  Creates task file (BEFORE dispatch) → Dispatches async →
  Sends status notification → Returns to owner (not blocked) →
  Processes callbacks → Updates status → Quality review →
  Delivers result [PENDING APPROVAL] → Owner approves → Execute

Signals

Task File

Each task: tasks/T-{YYYYMMDD}-{HHMM}.md — the single source of truth.

# T-{id}: {task name}
status: in_progress | completed | cancelled
dispatched: {YYYY-MM-DD HH:MM}
route: {channel}:{thread}
callback_to: {Leader session key}
notification_status_msg: {messageId}
notification_result_msg: {messageId}

## Steps
1. [⏳] agent:{id} → {description}
   brief_to: agent:{id}:main
   output: {result summary}
   files: {paths}

Full protocol (Leader's operating instructions): workspace/AGENTS.md (runtime) or templates/leader/AGENTS.md (source) Brief templates: shared/operations/brief-templates.md (runtime) or references/brief-templates.md (source) Approval pipeline: shared/operations/approval-workflow.md (runtime) or references/approval-workflow.md (source) Architecture and signals: references/architecture.md, references/signals.md (skill source)

Adding Agents Post-Setup

From Template Catalog

Say: "Add a Senior Developer agent" or "Add a Researcher to the team"

The kit will:

1. Create workspace from template
2. Inject orchestration rules
3. Update openclaw.json
4. Restart gateway

Custom Agent

Say: "Add a custom agent: Security Auditor"

The kit will:

1. Create workspace from blank template
2. Guide through role definition (capabilities, output format, boundaries)
3. Inject orchestration rules
4. Update config

From Agency Agents Catalog

Users can import agent templates from the Agency Agents repo. The scaffold script can inject orchestration compliance rules into any external agent template:

bash scripts/scaffold.sh --inject-orchestration \x3Cpath-to-agent.md>

Directory Structure After Installation

~/.openclaw/
├── openclaw.json                     # Updated with agent configs
├── workspace/                        # Leader
│   ├── SOUL.md, AGENTS.md
│   ├── HEARTBEAT.md                  # Task status check procedure
│   ├── tasks/, tasks/archive/
│   └── shared/
│       ├── INSTANCE.md               # Owner name, timezone, language
│       └── operations/
│           ├── channel-map.md
│           ├── team-roster.md
│           ├── communication-signals.md
│           ├── brief-templates.md
│           └── approval-workflow.md
├── workspace-executor/
│   ├── SOUL.md, AGENTS.md
│   └── shared -> ../workspace/shared/
├── workspace-reviewer/               # On-demand (spawned by Leader)
│   ├── SOUL.md, AGENTS.md
│   └── shared -> ../workspace/shared/
├── workspace-{specialist}/           # Per specialist
│   ├── SOUL.md, AGENTS.md
│   └── shared -> ../workspace/shared/

Scripts

Customization

Agent Behavior

Each agent has two files:

• SOUL.md — Persona, philosophy, boundaries. Freely editable.
• AGENTS.md — Operating procedures. Contains two sections:
  • Orchestration Protocol (auto-injected) — preserve this section
  • Role-Specific Instructions — freely editable

Notification Format

Status message format and result delivery templates are in references/brief-templates.md. Customize the owner-facing templates to match your communication language and style.

Approval Workflow

See references/approval-workflow.md for the full pipeline. Key customization points:

• Approval shortcuts (what phrases count as "approve")
• Stale approval timeout (default: 48h)
• Auto-approve rules (if any)