Agent Orchestration Kit

Set up and manage multi-agent task orchestration on OpenClaw with async dispatch, leader coordination, real-time tracking, and approval workflows.

Security Scan

The skill's files and runtime instructions are internally consistent with its stated purpose (scaffolding and configuring a multi-agent orchestration setup), but it will make non-trivial changes to your ~/.openclaw config and workspaces — preview and back up before applying.

Purpose & Capability

The name/description (agent orchestration) match the included artifacts: scaffolding templates, AGENTS/SOUL templates, a bash scaffold script, and a Node config patcher that merges orchestration settings into ~/.openclaw/openclaw.json. The declared runtime need for 'node' aligns with scripts/patch-config.js. Nothing requested is unrelated to building or registering multi-agent teams.

Instruction Scope

SKILL.md explicitly instructs creating workspaces, copying templates, and merging changes into the global OpenClaw config (~/.openclaw/openclaw.json). It enables agent-to-agent features (tools.agentToAgent) and sets sessions visibility to 'all', and recommends persistent async sessions and larger token budgets. These are coherent for orchestration, but they expand inter-agent visibility and session behavior beyond defaults — review those changes if you need tighter isolation.

Install Mechanism

This is instruction-only with two local scripts bundled (bash + Node). There is no network download, no external package fetching, and no installer that pulls code from untrusted URLs. Risk is limited to the local scripts writing to your OpenClaw directories.

Credentials

The skill requires no additional credentials or secret environment variables. It relies on standard local state (HOME, ~/.openclaw) and the presence of node/bash. The patcher reads/writes openclaw.json as intended for configuration; no unexplained secret access is requested.

Persistence & Privilege

The patch-config script modifies the global OpenClaw config (agents.list, tools.agentToAgent, sessions visibility, hooks, exec trusted dirs, session token budgets). That level of persistent change is expected for an orchestration onboarding flow but is materially impactful — it's not 'always: true' and will only run if invoked, but it does alter system-wide config and enable internal hooks.

Assessment

This kit appears to be what it says: scaffolding + config merges to enable a leader/spoke orchestration model. Before running anything: 1) Run the provided dry-run options (scripts/patch-config.js --dry-run and scaffold.sh --dry-run) and carefully inspect the output. 2) Back up ~/.openclaw/openclaw.json and any AGENTS.md/SOUL.md files that may be modified. 3) Pay attention to two changes that have security/visibility implications: tools.agentToAgent.enabled and tools.sessions.visibility = "all" (these increase inter-agent visibility), and the large parentForkMaxTokens value (increases token budget for forks). If you want stricter isolation, edit the scripts or config before applying (e.g., limit the agent allow list, set sessions.visibility to a narrower option). 4) Confirm that you trust the local scripts — patch-config.js uses child_process.execSync only to run 'openclaw --version' (a benign version check) and otherwise performs filesystem merges. 5) If unsure, run these scripts in a sandbox or manual mode and review diffs before writing files. Overall: internally coherent but make a backup and review the dry-run outputs before applying.

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"] } } }

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).

Team	Specialists	Best For
Software Dev	Senior Developer, Software Architect	Code-centric projects
Content Studio	Content Creator, Researcher	Content production workflows
Research & Analysis	Researcher	Investigation and deep analysis
Minimal	(none — add agents later)	Custom setups, start lean

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 <selected-team>

# For named leader workspaces:
# bash scripts/scaffold.sh --skill-dir "$(pwd)" --team <selected-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:

Config Key	What It Sets	Why
agents.defaults	compaction: safeguard, timeout: 1800s, maxConcurrent: 4	Stable defaults for multi-agent operation
agents.list[]	Agent entries (id, name, workspace, tools.deny)	Register each agent with OpenClaw
tools.agentToAgent	enabled: true, allow list	Enable inter-agent communication
tools.sessions	visibility: "all"	Agents can see each other's sessions
tools.exec.safeBinTrustedDirs	/bin, /usr/bin, /opt/homebrew/bin, /usr/local/bin	Trusted paths for CLI execution
session.agentToAgent	maxPingPongTurns: 3	A2A session ping-pong limit
session.parentForkMaxTokens	100000	Fork token budget
hooks.internal	boot-md, bootstrap, command-logger, session-memory	Enable internal hooks
messages.ackReactionScope	"all"	Acknowledgment on all messages
commands	native: "auto", nativeSkills: "auto", restart: true	Native command settings
agents.defaults.heartbeat	every: "3m", target: "last"	Heartbeat interval for task status checking

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-<timestamp> ~/.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:

Template	Source	Description
Senior Developer	Built-in	Full-stack implementation, TDD, code quality
Software Architect	Built-in	System design, ADRs, trade-off analysis
Code Reviewer	Built-in	Code review, security audit, quality assessment
Content Creator	Built-in	Copywriting, visual direction, platform packaging
Researcher	Built-in	Market research, analysis, evidence-based briefs
Custom	Blank template	Define your own role
Agency Agents	External	100+ templates from agency-agents

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

Signal	Meaning	Leader Action
[READY]	Complete and confident	Quality review → deliver or rework
[BLOCKED]	Cannot proceed	Assess alternative, re-route, or escalate
[NEEDS_INFO]	Needs more context	Gather info, re-brief
[LOW_CONFIDENCE]	Delivered but uncertain	Careful review, consider Reviewer
[SCOPE_FLAG]	Task bigger than expected	Reassess scope with owner
[APPROVE]	Reviewer approves	Mark [PENDING APPROVAL], present to owner
[REVISE]	Reviewer requests changes	Compose revision request to original agent
[PENDING APPROVAL]	Awaiting owner approval	Hold until owner responds
[CONTEXT_LOST]	Session compacted	Re-send task context from task file

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 <path-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

Script	Purpose	When to Run
scripts/scaffold.sh	Create directories, copy templates, inject orchestration rules	Initial setup, adding agents
scripts/patch-config.js	Merge agent config into openclaw.json	Initial setup, adding agents

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)