Skill: bill492/sub-agents (version 1.0.0)

--- name: sub-agents description: Spawn and coordinate sub-agent sessions for parallel work. Use when delegating tasks (research, code, analysis), routing to appropriate models, or managing multi-agent workflows. Trigger on "spawn", "sub-agent", "delegate", "parallel tasks", or when a task would benefit from a different model. --- # Sub-Agent Orchestration Spawn isolated sessions to execute tasks in parallel with appropriate model routing. ## Critical: Sub-Agents Are Context-Blind Sub-agents **do not** see AGENTS.md, SKILL.md, SOUL.md, MEMORY.md, or any workspace context files. They only see: 1. The `task` string you provide 2. Whatever files you tell them to read (via paths in the task) 3. Inline `attachments` you pass at spawn time **Everything the sub-agent needs must be in the task spec or explicitly referenced as a file path.** This includes output instructions, announce behavior, constraints, and domain knowledge. ## When to Spawn **Spawn when:** - Task benefits from a specialized model (code → Codex, research → Sonnet) - Work can run in parallel while you continue - Task is self-contained with clear success criteria - Will block you for >10 seconds (the 10-Second Rule) **Don't spawn when:** - Trivial one-liner (just do it yourself) - Task requires real-time conversation with the user - Heavy coordination overhead exceeds benefit ## Model Selection | Task Type | Model (alias) | Full path | Notes | |-----------|---------------|-----------|-------| | **Browser automation** | `gpt54` | `openai-codex/gpt-5.4` | **Default for all browser tasks.** Native computer-use. thinking: high auto-applied. | | Code implementation | `codex` | `openai-codex/gpt-5.3-codex` | Optimized for code gen | | Quick code/bugs | `codex` | `openai-codex/gpt-5.3-codex-spark` | Faster, simpler tasks | | Research, writing, quick tasks | `gpt5` | `openai-codex/gpt-5.2` | **Unlimited on Codex sub.** Replaces sonnet/haiku for most work. | | Complex reasoning | `opus` | `anthropic/claude-opus-4-6` | Deep analysis (expensive) | | Huge context (>200K tokens) | `sonnet` | `anthropic/claude-sonnet-4-5` | 1M context window fallback | Use aliases when available. GPT-5.2 is unlimited on the Codex subscription — prefer it over Sonnet/Haiku for sub-agents unless you specifically need Sonnet's 1M context window. ## sessions_spawn Parameters | Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | `task` | ✅ | — | The full task description (only context the sub-agent gets) | | `model` | — | parent model | Model alias or full provider/model path | | `thinking` | — | — | `off \| low \| medium \| high` | | `label` | — | — | Label for logs/UI tracking | | `runTimeoutSeconds` | — | config default or `0` | Abort after N seconds | | `cleanup` | — | `keep` | `delete \| keep` — delete removes session after completion | | `thread` | — | `false` | Thread-bound routing (Discord/Slack) | | `mode` | — | `run` | `run \| session` — defaults to `session` when `thread=true` | | `sandbox` | — | `inherit` | `inherit \| require` — require rejects if child isn't sandboxed | | `agentId` | — | current agent | Spawn under another agent (must be in allowlist) | | `attachments` | — | — | Inline files: `[{ name, content, encoding?, mimeType? }]` | ### Key behaviors - **Always non-blocking.** Returns `{ status: "accepted", runId, childSessionKey }` immediately. - **Sub-agents cannot spawn sub-agents.** No nested spawning. Plan accordingly. - **Sub-agents get all tools EXCEPT session tools** (no sessions_list/history/send/spawn). Configurable via `tools.subagents.tools`. - **Auto-archive:** Sessions archive after `agents.defaults.subagents.archiveAfterMinutes` (default: 60). ## Announce Mechanism After a sub-agent completes, OpenClaw runs an **announce step** that posts results to the requester's chat channel. - Announce replies are normalized to **Status / Result / Notes** format - **Status** comes from runtime outcome (success/failure/timeout), not model text - If the assistant's final reply is empty, the latest `toolResult` is used as Result - Include a stats line (runtime, tokens, sessionKey, cost) ### Controlling announce behavior | Sub-agent replies with... | Effect | |---------------------------|--------| | Normal text | Posted to requester's channel as the announce | | `ANNOUNCE_SKIP` | Announce is suppressed — nothing posted | | Empty reply | Latest toolResult becomes the Result | **⚠️ Use `ANNOUNCE_SKIP`, not `NO_REPLY`.** `ANNOUNCE_SKIP` is the specific mechanism for sub-agent announce suppression. `NO_REPLY` is a general silent-reply convention that may not suppress the announce step. ## Task Specification — Structured Handoff Protocol Every spawn should follow this template. Remember: this is the **only context** the sub-agent receives. ### Required Fields 1. **Objective** — One sentence. What the sub-agent must accomplish. 2. **Context** — Structured facts. File paths, API endpoints, constraints, relevant decisions. Not narrative — a reference sheet. 3. **Inputs** — What files/data to read before starting. Be specific: paths, line ranges, sections. 4. **Success criteria** — How to verify done. Testable, not subjective. 5. **Output contract** — Where and how to deliver results. File path, format, schema. ### Optional Fields 6. **Constraints** — What NOT to do. Boundaries, things that already failed. 7. **Domain knowledge** — Project-specific context files to load (e.g., `projects/foo/CONTEXT.md`). 8. **Decisions already made** — Prevent re-litigating settled questions. ### Announce instructions (include in every task) For silent sub-agents (results consolidated by parent): ``` Write your full analysis to [path]. Your final reply after writing the file should be ONLY: ANNOUNCE_SKIP ``` For sub-agents that should announce their own results: ``` Write results to [path]. Your final reply should summarize what you found — this will be posted to the chat. ``` ### Example (Good) ``` OBJECTIVE: Analyze time-of-day patterns in Kalshi BTC spread bot single-fill losses. CONTEXT: - Bot code: projects/kalshi-arb/bot/spread_bot.py - Trade log: projects/kalshi-arb/data/trades.csv (columns: timestamp, action, side, price, fill_type, pnl) - Key finding: single-fills have 1.8% win rate vs ~83% for dual-fills - Volume gate already exists at 150K trailing-1 INPUTS: - Read trades.csv, filter to fill_type="single" - Read spread_bot.py lines 180-220 (gating logic) SUCCESS CRITERIA: - Statistical breakdown of single-fill losses by hour (ET) - Identify if specific time windows have >2x the loss rate - Chi-squared or equivalent significance test OUTPUT: - Write analysis to projects/kalshi-arb/time-gating-analysis.md - Include raw data table + recommendation CONSTRAINTS: - Don't modify bot code, analysis only - Flag if sample size < 30 per bucket Your final reply after writing the file should be ONLY: ANNOUNCE_SKIP ``` ### Example (Bad — Don't Do This) ``` Look at the Kalshi bot trades and figure out if time of day matters for single fills. The bot is in the projects folder somewhere. Write up what you find. ``` The bad example forces the sub-agent to guess file locations, decide its own success criteria, and has no announce instructions. ## Monitoring & Management ### `subagents` tool (primary orchestration) ``` subagents(action="list") // List active sub-agents subagents(action="steer", target="<id>", message="...") // Send follow-up instructions subagents(action="kill", target="<id>") // Kill a running sub-agent ``` ### Session tools (for history/cross-session) ``` sessions_list({ kinds: ["other"], activeMinutes: 60 }) // Sub-agents are kind "other" sessions_history({ sessionKey: "...", limit: 5 }) // Check output sessions_send({ sessionKey: "...", message: "..." }) // Send to any session ``` ### Discovery ``` agents_list() // Discover which agentIds are allowed for sessions_spawn ``` **Don't poll in loops.** Check on-demand, when prompted, or for debugging. ## Fallback Rules If a model is rate-limited: 1. **Codex/GPT-5.2 limited** → Use `sonnet` for code/research tasks 2. **Sonnet limited** → Use `gpt5` for research tasks 3. **All limited** → Use `opus` directly (last resort, expensive) Rate limits typically reset in 30-90 minutes. ## Anti-Patterns ❌ **Spawning for trivial tasks** — Just do simple things yourself ❌ **Vague task specs** — "Look into X" without success criteria or output contract ❌ **Over-parallelization** — Too many concurrent spawns = memory pressure ❌ **Forgetting announce instructions** — Every task must specify ANNOUNCE_SKIP or what to say ❌ **Assuming sub-agents have context** — They don't see your workspace files ❌ **Using `kinds: ["isolated"]`** — The correct kind for sub-agents is `"other"` ❌ **Using `NO_REPLY` for announce suppression** — Use `ANNOUNCE_SKIP` ❌ **Expecting sub-agents to spawn their own sub-agents** — They can't

path: references/models.md
content: # Model Reference

Detailed model information for sub-agent routing decisions.

## Available Models

### Anthropic

| Model | Alias | Input/MTok | Output/MTok | Context | Best For |
|-------|-------|------------|-------------|---------|----------|
| claude-opus-4-5 | `opus` | $5 | $25 | 200K | Complex reasoning, architecture |
| claude-sonnet-4-5 | `sonnet` | $3 | $15 | 1M | Research, synthesis, long docs |
| claude-haiku-4-5 | `haiku` | $1 | $5 | 200K | Quick tasks, simple transforms |

### OpenAI (via Codex subscription)

| Model | Alias | Pricing | Context | Best For |
|-------|-------|---------|---------|----------|
| gpt-5.2-codex | `codex` | Subscription | 128K | Code generation, implementation |
| gpt-5.2 | `gpt5` | Subscription | 128K | General tasks |

## Thinking Levels

Control reasoning depth with the `thinking` parameter:

| Level | Behavior | Use When |
|-------|----------|----------|
| `off` | No extended thinking | Simple, fast tasks |
| `low` | Light reasoning | Most routine work |
| `medium` | Moderate reasoning | Complex but bounded problems |
| `high` | Deep reasoning | Architecture, complex debugging |

Higher thinking = more tokens = more cost/time. Match to task complexity.

## Model Characteristics

### Codex (gpt-5.2-codex)
- **Strengths:** Code generation, refactoring, test writing, debugging
- **Weaknesses:** May over-engineer simple tasks
- **Tips:** Give clear file paths, existing patterns to follow

### Sonnet (claude-sonnet-4-5)
- **Strengths:** Research synthesis, long document analysis, balanced cost/capability
- **Weaknesses:** Not as strong at code as Codex
- **Tips:** Great for GitHub issues, documentation, data analysis

### Haiku (claude-haiku-4-5)
- **Strengths:** Speed, cost efficiency, simple transformations
- **Weaknesses:** May miss nuance on complex tasks
- **Tips:** Use for formatting, simple lookups, quick validations

### Opus (claude-opus-4-5)
- **Strengths:** Deepest reasoning, complex multi-step problems
- **Weaknesses:** Expensive, slower
- **Tips:** Reserve for truly complex coordination, not routine work

## Cost Awareness

Rough token estimates for common tasks:
- Simple code task: ~2K input, ~1K output
- Research task: ~5K input, ~3K output  
- Complex implementation: ~10K input, ~5K output

**Cost formula:** `(input_tokens × input_rate + output_tokens × output_rate) / 1,000,000`

Example: Sonnet research task
- Input: 5K × $3 = $0.015
- Output: 3K × $15 = $0.045
- Total: ~$0.06 per task

## Rate Limits

Rate limits vary by provider and tier. Common patterns:
- Anthropic: Requests/min and tokens/min limits
- OpenAI Codex: Daily usage caps on subscription tier

When you hit a limit:
1. Check error message for reset timing
2. Switch to fallback model
3. Or wait for reset (usually 30-90 min)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)