# Send Task Router Skill to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "task-router-skill",
    "name": "Task Router Skill",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/capt-marbles/task-router-skill",
    "canonicalUrl": "https://clawhub.ai/capt-marbles/task-router-skill",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/task-router-skill",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=task-router-skill",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "task-router-skill",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-04T01:22:07.754Z",
      "expiresAt": "2026-05-11T01:22:07.754Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=task-router-skill",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=task-router-skill",
        "contentDisposition": "attachment; filename=\"task-router-skill-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "task-router-skill"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/task-router-skill"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/task-router-skill",
    "downloadUrl": "https://openagent3.xyz/downloads/task-router-skill",
    "agentUrl": "https://openagent3.xyz/skills/task-router-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/task-router-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/task-router-skill/agent.md"
  }
}
```
## Documentation

### Task Router

Distributed task queue for OpenClaw multi-agent systems. Central coordination, async handoffs, capability-based routing.

### Quick Start

# Install skill
clawhub install task-router

# Register an agent
task agent register watson --capabilities "research analysis" --max-concurrent 3

# Create a task
task create --type research --title "Competitor analysis" --priority high

# Router runs automatically via heartbeat
# Check task status
task list --status pending
task show task-abc123

### What This Does

Core Functions:

Enqueue: Create tasks from any session (main or sub-agent)
Route: Match tasks to agents by capabilities
Track: Monitor task lifecycle (pending → active → complete/failed)
Async Coordination: Hand off work, check back later
Dead Letter: Handle timeouts and failures
Rebalance: Move stuck tasks, retry with fallbacks

Use Cases:

Heartbeat creates research task → auto-routes to research agent
Main agent spawns work → goes async, checks later
Multi-step workflows: Task A output → Task B input
Agent failure → task reassigned to backup agent
Load balancing across multiple agents with same capabilities

### File Layout

~/.openclaw/task-router/
├── config.yaml           # Router settings, timeouts
├── agents.yaml           # Agent registry + capabilities
├── queue/                # Task state
│   ├── pending/          # Waiting for assignment
│   ├── active/           # Assigned to agent
│   ├── completed/        # Finished successfully
│   └── failed/           # Failed, exhausted retries
└── logs/
    └── router.log        # Routing decisions

### config.yaml

router:
  check_interval: 30           # Seconds between router runs
  default_ttl: 3600            # Default task timeout
  max_retries: 2
  
  strategies:
    default: least-loaded      # round-robin | least-loaded | priority
    by_type:
      research: least-loaded
      image_gen: round-robin
      urgent: priority

  health:
    agent_timeout: 300           # Mark agent unhealthy after seconds
    task_timeout:
      warning: 1800              # Alert at 30 min
      critical: 3600             # Fail at 1 hour

  notifications:
    on_complete: true
    on_fail: true
    channels: [main_session]   # Could add Discord, etc.

### agents.yaml (auto-maintained)

agents:
  watson:
    id: watson
    emoji: 🔬
    capabilities: [research, analysis, web_search]
    max_concurrent: 3
    current_tasks: [task-abc123, task-def456]
    stats:
      completed: 47
      failed: 2
      avg_duration: 180
    health:
      last_ping: 2026-02-13T09:15:00Z
      status: healthy
    
  picasso:
    id: picasso
    emoji: 🎨
    capabilities: [image_gen, image_edit]
    max_concurrent: 2
    current_tasks: []

### Task Schema

id: task-abc123
type: research               # Matches agent capability
title: Research Gameye competitors
description: Deep competitive analysis

payload:
  query: Gameye vs competitors
  sources: [web, apollo]
  output_format: markdown
  
created_by: main             # Session label that created it
assigned_to: watson          # null until routed
assigned_by: router          # router | manual | agent

created_at: 2026-02-13T09:00:00Z
assigned_at: 2026-02-13T09:05:00Z
started_at: 2026-02-13T09:06:00Z
completed_at: null
expires_at: 2026-02-13T10:00:00Z  # created_at + ttl

priority: high               # low | normal | high | urgent
ttl: 3600                    # Seconds
retries: 0
max_retries: 2

dependencies: []             # Block until these complete
blocked_by: []               # Populated by router

status: assigned             # pending | assigned | running | complete | failed
result: null                 # Path to result file
error: null                  # Error message if failed

metadata:
  source: heartbeat
  tags: [gameye, competitors]

### Task Management

# Create task
task create --type research \\
  --title "Research Gameye competitors" \\
  --data '{"query": "Gameye pricing"}' \\
  --priority high \\
  --ttl 3600

# Create with dependencies
task create --type analysis \\
  --title "Analyze research results" \\
  --depends-on task-abc123

# List tasks
task list                    # All non-completed
task list --status pending
task list --assigned-to watson
task list --type research --limit 10
task list --created-after 2026-02-13

# Show task
task show task-abc123        # Full details + result preview

# Manage tasks
task cancel task-abc123      # Cancel pending or active
task retry task-abc123       # Move failed back to pending
task reprioritize task-abc123 --priority urgent

# Results
task result task-abc123      # View result file
task export --status completed --since 2026-02-13 > ~/reports/tasks.ndjson

### Agent Management

# Register agent (required before routing)
task agent register watson \\
  --capabilities "research analysis web_search" \\
  --max-concurrent 3 \\
  --emoji 🔬

# Update agent
task agent update watson --add-capability "competitive-analysis"
task agent update watson --max-concurrent 5

# Check agent health
task agent status watson     # Current tasks, health, stats
task agent ping watson       # Health check ping

# List agents
task agent list              # All agents
task agent list --capable-of research

# Unregister
task agent unregister watson --reassign-tasks

### Router Control

# Status
task router status           # Queue depth, agent health

# Control flow
task router pause            # Stop new assignments
task router resume           # Resume routing
task router rebalance        # Redistribute stuck tasks

# Maintenance  
task router cleanup          # Archive old completed tasks
task router drain            # Finish active, no new pending

### Programmatic API

import * as Task from "~/.openclaw/task-router/sdk";

// === Creating Tasks ===

// Simple create
const task = await Task.create({
  type: "research",
  title: "Competitor analysis",
  payload: { query: "Gameye vs competitors" }
});

// With options
const task = await Task.create({
  type: "image_gen",
  title: "Generate hero image",
  payload: { prompt: "Futuristic game server...", size: "1024x1024" },
  priority: "high",
  ttl: 1800,
  max_retries: 1,
  dependencies: [previousTaskId],  // Waits for these first
  created_by: "main"
});

// === Querying ===

// Get status
const status = await Task.status(task.id);
// { id, status, assigned_to, created_at, expires_at }

// Wait for completion (blocking)
const result = await Task.wait(task.id, { timeout: 300, pollInterval: 5 });

// List with filters
const pending = await Task.query({
  status: "pending",
  type: "research",
  priority: "high",
  limit: 10
});

const myTasks = await Task.query({
  created_by: "main",
  status: ["assigned", "running"]
});

// === Agent Integration ===

// Agent picks up work (if auto-assign disabled)
await Task.claim({
  agentId: "watson",
  capableOf: "research",
  limit: 1
});

// Complete task
await Task.complete(task.id, {
  result_path: "~/agents/watson/memory/results/competitors.md",
  summary: "Found 5 competitors: GameLift, Multiplay, Hathora, Edgegap, Agones",
  metadata: { competitors_count: 5 }
});

// Fail task
await Task.fail(task.id, {
  reason: "API quota exceeded",
  retryable: true  // Will auto-retry
});

// === Multi-Step Workflows ===

// Chain tasks
const analysisTask = await Task.chain(researchTask.id, {
  type: "analysis",
  title: "Analyze research findings",
  payload: { input_task: researchTask.id }
});

// Parallel tasks
const tasks = await Task.parallel([
  { type: "research", title: "Research A", payload: {} },
  { type: "research", title: "Research B", payload: {} },
  { type: "research", title: "Research C", payload: {} }
]);
await Task.waitAll(tasks.map(t => t.id));

// === Agent Session Integration ===

// Spawn via task router (recommended for async work)
const spawnResult = await Task.spawn({
  taskId: task.id,
  agentId: "watson",      // Optional: auto-route if omitted
  useSession: true      // Use sessions_spawn vs sessions_send
});

// Router will call:
// sessions_spawn({ agentId, task, label: task.id })

### HEARTBEAT Integration

Create ~/.openclaw/workspace/HEARTBEAT.md:

# Task Router Heartbeat

## Router Cycle (runs every 30s)
\`\`\`typescript
import * as Task from "~/.openclaw/task-router/sdk";

// 1. Auto-route pending tasks
const routed = await Task.router.cycle();
if (routed.length > 0) {
  Task.log(\`Routed ${routed.length} tasks:\`, routed.map(t => \`${t.id} → ${t.assigned_to}\`));
}

// 2. Check for timeouts
const timeouts = await Task.router.checkTimeouts();
for (const task of timeouts) {
  if (task.retries < task.max_retries) {
    Task.log(\`Retrying ${task.id} after timeout\`);
    await Task.retry(task.id);
  } else {
    Task.log(\`Dead lettering ${task.id}\`);
    await Task.router.moveToDeadLetter(task);
  }
}

// 3. Check agent health
const unhealthy = await Task.agents.checkHealth();
for (const agent of unhealthy) {
  // Reassign their tasks
  await Task.router.reassignFrom(agent.id);
}

// 4. Notify on completions
const recent = await Task.query({
  status: "completed",
  completed_after: Date.now() - 60000  // Last minute
});
for (const task of recent) {
  if (task.created_by === "main") {
    sessions_send({
      message: \`✅ Task complete: ${task.title}\\nResult: ${task.result}\`
    });
  }
}

### Routing Strategies

StrategyUse CaseDescriptionround-robinEven loadCycle through agentsleast-loadedPrevent overloadAgent with fewest active tasksfastestLatency criticalAgent with best completion timepriorityUrgent tasksSort by priority firststickySequential workSame agent for related tasks

# config.yaml
strategies:
  default: least-loaded
  
  # Per-task-type strategies
  by_type:
    research: least-loaded      # Don't overwhelm one researcher
    image_gen: round-robin      # Even GPU utilization
    urgent: priority             # Always pick best agent
    
  # Custom rules
  rules:
    - if: priority == urgent
      then: fastest
    - if: tags includes "sticky"
      then: sticky

### Task Lifecycle Details

PENDING ──assign──→ ASSIGNED ──ack──→ RUNNING ──complete──→ COMPLETE
   │           │          │              │                      │
   │           │          │              └──fail────┐            │
   │           │          │                        ↓            │
   │           │          │                     FAILED ──retry──┘
 timeout      │       timeout        (if retries < max)        │
   │           │          │                (else dead letter)    │
   │           │          │                                     │
   └───────────┴──────────┘─────────────────────────────────────┘

State Definitions:

pending: Created, waiting for router
assigned: Routed to agent, waiting for acceptance
running: Agent acknowledged, working on it
complete: Success, result available
failed: Final failure (retries exhausted)
dead_letter: Failed permanently, needs manual review

### Dead Letter Queue

When a task exhausts retries:

~/.openclaw/task-router/dead-letter/
├── task-failed-001.yaml       # Task with final error state
├── task-failed-002.yaml
└── index.yaml                 # Summary for admin review

# Review failed tasks
task dead-letter list
task dead-letter show task-failed-001

# Actions
task dead-letter retry task-failed-001      # Force retry
task dead-letter reassign task-failed-001 --to watson
task dead-letter archive task-failed-001   # Ack and archive

### Best Practices

Task Design:

Keep payloads JSON-serializable (no circular refs)
Include output format hints in payload
Use dependencies for true sequencing
Set reasonable TTLs (don't block forever)

Agent Design:

Register capabilities narrowly at first
Set conservative max_concurrent
Heartbeat should check for assigned tasks
Always acknowledge → complete/fail cleanly

Coordination Patterns:

Use Task.spawn() for fire-and-forget
Use Task.wait() when user needs result now
Chain dependent tasks vs one mega-task
Let router handle retries, not agents

### Multi-Agent Example

// User asks: "Research competitors and create a presentation"

// Main agent (you) orchestrates:

// 1. Create research tasks
const research = await Task.create({
  type: "research",
  title: "Research Gameye competitors",
  payload: { query: "Gameye vs competitors" }
});

// 2. Create analysis task (depends on research)
const analysis = await Task.create({
  type: "analysis",
  title: "Analyze competitive landscape",
  dependencies: [research.id],
  payload: { input_task: research.id }
});

// 3. Create image task (independent, async)
const images = await Task.parallel([
  { type: "image_gen", title: "Competitor comparison chart", payload: {} },
  { type: "image_gen", title: "Market positioning diagram", payload: {} }
]);

// 4. Create presentation task (depends on all above)
const deck = await Task.create({
  type: "presentation",
  title: "Gameye competitive analysis deck",
  dependencies: [analysis.id, ...images.map(i => i.id)],
  payload: { 
    research: analysis.id,
    images: images.map(i => i.result)
  }
});

// 5. Wait for final result
const result = await Task.wait(deck.id, { timeout: 600 });

// Result: orchestrated 4 agents, 5 tasks, handled dependencies

### Troubleshooting

# Nothing routing?
task router status           # Check paused?
task agent list             # Any healthy agents?
task list --status pending  # Tasks waiting?

# Task stuck?
task show task-abc123        # Check assigned_to, started_at
task agent status watson     # Is agent healthy?

# Agent not picking up?
# - Check agent's HEARTBEAT checks for tasks
# - Verify sessions_send to agent works

# Too many failures?
task dead-letter list       # Review patterns
task router logs            # See routing decisions

# Clear everything (nuke)
task router drain           # Wait for active
task list --status pending | xargs task cancel
task dead-letter clear

### Requirements

OpenClaw with sessions_send/sessions_spawn/sessions_list
Agents with proper HEARTBEAT.md checking for tasks
Optional: cron job for router if heartbeat not reliable

### Future Extensions

Metrics: Prometheus-compatible stats
Web UI: Dashboard at localhost:3333
Plugins: Slack/Discord notifications
**Priority Queues
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: capt-marbles
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-04T01:22:07.754Z
- Expires at: 2026-05-11T01:22:07.754Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/task-router-skill)
- [Send to Agent page](https://openagent3.xyz/skills/task-router-skill/agent)
- [JSON manifest](https://openagent3.xyz/skills/task-router-skill/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/task-router-skill/agent.md)
- [Download page](https://openagent3.xyz/downloads/task-router-skill)