Agency Agents Router -- Route and orchestrate specialized agents

Repo：Staok/agency-agents-router-skill.

Overview

If openclaw.json has multiple agents configured under agents.list, this skill discovers them and orchestrates appropriate agents for any given task.

In a default OpenClaw setup, only the main agent's prompt is active. Other configured agents are invisible. Agent Router solves this by injecting agent awareness and orchestration logic into the main agent's prompt.

Prerequisites

This skill is the router — the agent definitions must be installed separately. Without them, agents.json will be empty and no orchestration can happen.

User (manual): Install agency-agents-zh agents, then restart gateway:

git clone https://github.com/jnMetaCode/agency-agents-zh.git
cd agency-agents-zh
./scripts/convert.sh --tool openclaw
./scripts/install.sh --tool openclaw

# Restart OpenClaw gateway
openclaw gateway restart

Agent (auto): After user confirms installation, the agent runs:

cd ~/.openclaw/workspace/skills/agency-agents-router
python3 scripts/rebuild_index.py --clone

Then verifies agents appear in ~/.openclaw/openclaw.json under agents.list.

If agents.json is missing or empty, the agent MUST first check whether agency-agents-zh is installed. If not, instruct the user with the manual steps above. Do NOT attempt to orchestrate without agents.

How It Works

The main agent, equipped with this skill, becomes an orchestrator:

1. Receive a task description
2. Classify the task intent using the Task Archetypes table — this determines the agent selection strategy
3. Detect ambiguity: if the task crosses archetype boundaries, ask ONE clarifying question (audience, genre, format, depth) then proceed
4. Pre-research: for factual or time-sensitive tasks, the orchestrator should do live web searches first to ground agents in current reality, not stale training data
5. Look up agents.json to find matching agents based on the clarified intent
6. Design an execution plan: which agents to run, in what order, with what dependencies
7. Execute via sessions_spawn(agentId=xxx, mode="run"); domain-expert agents should be prompted to use web_search / web_fetch for factual grounding
8. Aggregate results and present to the user

Research Protocol: Prefer Live Web Data

For factual, time-sensitive, or comparative tasks, agents should rely on live web data rather than training data alone.

When to search the web

Pre-research (orchestrator)

Before dispatching agents for factual tasks: 2-3 web_search queries → web_fetch 2-3 key sources → include findings in sub-agent prompts.

Sub-agent prompt boilerplate

Prefer web_search/web_fetch for latest information over training data.
Cite URLs and dates for factual claims.
Mark unverifiable items as "[待确认]".

CRITICAL: Classify BEFORE selecting agents

Do NOT jump from "receive task" directly to "look up agents". Without first classifying the task archetype, the same keyword ("write an analysis article") will be interpreted inconsistently — sometimes as research, sometimes as content creation. Step 2 (classification) is mandatory. Step 3 (ambiguity check) is mandatory when keywords span archetypes.

Task Archetypes

Every task MUST be classified into one of these archetypes BEFORE agent selection. The archetype determines the primary agent role and whether domain-expert agents play lead or supporting roles.

Decision Heuristic

When the task says "write an article about X analysis", ask yourself:

• Is the primary goal to inform and engage a broad audience? → Content Creation (narrative agents lead, domain experts support)
• Is the primary goal to produce a structured, evidence-heavy report for decision-makers? → Research & Analysis (domain experts lead)
• Is the audience implied by the user's profile? If the user is a content creator → Content Creation. If the user is an engineer → Research & Analysis. But still confirm if ambiguous.

Ambiguity Detection & Clarification Protocol

Trigger Keywords

These keywords frequently span multiple archetypes. When detected, the orchestrator MUST ask for clarification before selecting agents:

Clarification Protocol

When ambiguity is detected:

1. Identify the ambiguous dimension(s): audience? genre? format? depth? technical level?
2. Ask that resolves all ambiguity at once — do not ask multiple rounds
3. Frame the question to reveal the archetype: "Is this for a general-audience publication (Content Creation) or a technical decision-making report (Research)?"
4. If the user's profile strongly suggests one archetype, still confirm if ambiguity crosses the Content/Research boundary

Bad (multiple rounds):

"Who is the audience?" → wait → "What format?" → wait → "How technical?"

Good (single round):

"Target audience and channel for this article? e.g., general readers on Zhihu/WeChat (Content Creation route), or technical decision-makers as an internal report (Research route)?"

Orchestration Patterns

Pattern 1: Single Agent

A task clearly falls under one agent's expertise. Spawn directly.

User: "Review this C++ code for bugs"
  Archetype: Engineering
  -> engineering-code-reviewer

Pattern 2: Parallel (Independent Agents)

Spawn multiple agents simultaneously for independent subtasks.

User: "Review this PR"
  -> engineering-code-reviewer (code quality)
  -> engineering-security-engineer (security audit)
  -> testing-performance-benchmarker (performance check)
  All three run in parallel, results merged at the end.

Pattern 3: Sequential / Pipeline

Agent B depends on Agent A's output. Spawn A first, feed result into B.

User: "Design and document this API"
  -> engineering-software-architect (design the API)
  -> engineering-technical-writer (document the design)

Pattern 4: DAG (Directed Acyclic Graph)

Complex workflows with parallel branches and merge points.

User: "Technical design review for a new feature"
  -> engineering-software-architect (system design)
     +-> engineering-security-engineer (security review)  --+
     +-> engineering-backend-architect (backend review)  ----+-> product-manager (summary)
     +-> engineering-database-optimizer (schema review)  ----+

Pattern 5: Multi-Perspective Analysis (Research)

Multiple disciplinary perspectives for evidence-heavy analysis. Domain experts should web-search for current data.

User: "Is an AI-powered note-taking app viable?"
  Pre-research: orchestrator web-searches market landscape
  -> product-trend-researcher (market analysis)
  -> engineering-software-architect (technical feasibility)
  -> finance-financial-forecaster (cost/revenue modeling)
  -> marketing-seo-specialist (go-to-market analysis)

Pattern 6: Content Creation

Narrative design + audience psychology + platform-aware execution. Domain experts play supporting roles (fact-checking, background research), NOT lead roles.

User: "Write a deep-dive article about AI Agent trends"
  Pre-research: orchestrator web-searches current landscape
  -> domain expert (background research — web-search for latest)
  -> academic-narratologist (story arc, hooks, rhythm)
  -> academic-psychologist (reader psychology, engagement)
  -> marketing-content-creator (platform voice, shareability)

  Workflow: orchestrator pre-research → domain expert FIRST (live web search) →
            creative agents in PARALLEL → synthesizer produces final draft.

Key distinction from Pattern 5 (Research):

Agent Index

The lookup table in agents.json maps every configured agent to:

Data sources: agency-agents-zh (194 agents) + agency-agents upstream (21 agents).

Usage Commands

For most tasks, no command is needed. Describe the task naturally and the main agent will determine the orchestration plan.

sessions_spawn Usage

sessions_spawn(agentId="\x3CagentId>", task="\x3Ctask description>", mode="run")

• Sub-agents execute in their own workspace
• Results return to the main session automatically
• Multiple spawn calls without inter-dependencies can be invoked in parallel (single turn)
• Dependent calls: spawn, wait for result, then spawn the next

Maintenance

# Rebuild with local agency-agents-zh repo:
python3 scripts/rebuild_index.py --repo /path/to/agency-agents-zh

# Auto-clone and rebuild from scratch:
python3 scripts/rebuild_index.py --clone --fetch

Credits

• Agent descriptions from agency-agents-zh (194 agents)
• Additional descriptions from agency-agents upstream (21 agents)
• Orchestration patterns inspired by Agency Orchestrator