Sub-agent Task Queue

Concurrent task queue management for sub-agent orchestration. Provides a /queue command for real-time visibility into active, queued, and completed sub-agent...

Security Scan

The skill's stated purpose (managing sub-agent tasks) matches the instructions, but the runtime guidance is vague about how to spawn/terminate sub-agents, omits any required permissions, and encourages aggressive queuing — creating risk of resource exhaustion and leakage of session/task data written to /tmp.

Purpose & Capability

The name/description (sub-agent task queue) aligns with the instructions which manage a /tmp JSON queue and describe spawn/complete/fail flows. However, the skill assumes the agent can 'spawn' and 'kill' sub-agents and record sub-agent session IDs without declaring the platform APIs, permissions, or credentials needed. That is a missing but necessary capability for the stated purpose.

Instruction Scope

SKILL.md directs creating and updating /tmp/task-queue.json, spawning sub-agents, moving tasks between lists, and terminating tasks, but it does not specify HOW to spawn or kill sessions (no safe API calls or permission boundaries). It also includes guidance to prefer queuing ('better to over-spawn'), which can lead to excessive resource consumption. Writing session IDs and task descriptions to /tmp could expose sensitive data to other local users/processes.

Install Mechanism

This is an instruction-only skill with no install spec and no downloaded code — lowest install risk. The README suggests copying the skill into a target agent's skills directory, which is an administrative action but not inherently dangerous.

Credentials

No environment variables or external credentials are requested in the manifest, which is reasonable. However, practical operation (spawning/killing sub-agents, modifying agent routing) will likely require platform permissions or tokens that are not declared; the omission creates ambiguity about required privileges.

Persistence & Privilege

The skill stores state in /tmp/task-queue.json (ephemeral by default) and recommends placing the skill into agents' skills directories and updating routing config. It does not request always:true or modify other skills directly, but writing session IDs and histories to disk could persist sensitive metadata beyond the chat session if /tmp isn't cleared.

What to consider before installing

This skill is plausibly what it claims to be, but it leaves key implementation and safety details unspecified. Before installing or enabling it: (1) confirm how your OpenClaw agent spawns and terminates sub-agents and what credentials/APIs are required — the skill does not declare or request them; (2) avoid running it on multi-user/shared machines or ensure /tmp is secure, because task descriptions and sub-agent session IDs are stored in /tmp and could leak; (3) set conservative maxConcurrent/maxSameType values and add quotas/rate limits to prevent runaway spawning and resource exhaustion; (4) decide and document the exact mechanism for killing sub-agents (platform API vs. OS process kill) to avoid unsafe commands; (5) test in an isolated environment first. If the author provides explicit, platform-specific spawn/kill APIs and a clear permissions list, the assessment could change to benign.

Task Queue

Manage concurrent sub-agent tasks with real-time visibility. Main session stays responsive; heavy work runs in parallel sub-agents tracked by a queue.

Setup

Initialize the queue state file on first use:

cat > /tmp/task-queue.json << 'EOF'
{
  "maxConcurrent": 8,
  "maxSameType": 3,
  "active": [],
  "queued": [],
  "completed": [],
  "stats": { "totalSpawned": 0, "totalCompleted": 0, "totalFailed": 0 },
  "updatedAt": null
}
EOF

Adjust maxConcurrent by machine:

• Low-end (Mac Mini 16GB): 3-4
• Mid-range (Mac Studio 64GB): 6
• Server (64+ cores, 128GB+): 8

Commands

Command	Action
/queue or /quene	Show current queue status
/queue clear	Clear completed task history
/queue kill <Q-ID>	Terminate a specific task

Queue Protocol

On new task (that needs sub-agent)

1. Generate sequential ID: Q-001, Q-002, ...
2. Classify type: research | dev | report | search | translate | analysis | other
3. Check capacity:
   • active.length < maxConcurrent AND same-type count < maxSameType → spawn, add to active
   • Otherwise → add to queued, notify user of position
4. Update /tmp/task-queue.json

On task completion

1. Move from active to completed (keep last 20)
2. Pop next from queued if any, spawn it
3. Update stats
4. Report result to user

On task failure

1. Record in completed with "result": "failed" and reason
2. Notify user with suggestion (retry / alternative / manual)
3. Continue dequeuing — failures don't block the queue

/queue response format

📋 任务队列 (活跃 X/8 | 排队 Y)

🔄 运行中：
  Q-001 [research] 海外媒体分析 (3m ago)
  Q-002 [dev] 修复登录bug (1m ago)

⏳ 排队中：
  Q-003 [report] 周报生成

✅ 最近完成：
  Q-000 [search] KOL筛选 → 成功 (5m)

If empty: report "全空，随时可以塞活"

Data Schema

See references/schema.md for the complete JSON structure of /tmp/task-queue.json.

Dispatch Rules

Decide whether to queue (spawn sub-agent) or handle directly in main session:

Queue it (any one triggers):

• Estimated time > 2 minutes
• Batch operations (bulk search, multi-doc processing)
• Development / code tasks
• Deep research or analysis
• Long document generation
• User sends multiple independent tasks at once

Handle directly (all true):

• Simple Q&A, chat, confirmations
• Quick lookups (read file, check status)
• 1-2 step operations
• Needs multi-turn clarification first

When uncertain, prefer queuing — better to over-spawn than block the main session.

Portable Deployment

To deploy on another machine (e.g., Mac with a different OpenClaw agent):

1. Install this skill to the target agent's skills directory
2. Create /tmp/task-queue.json with the init template above
3. Adjust maxConcurrent for the machine's resources
4. Add /queue trigger to the agent's routing config (AGENTS.md or equivalent)