subagent-task-worker
Pitfalls, examples, and edge cases for workers executing a Surogates subagent task. Loaded automatically when the dispatcher spawns a session bound to a Task (Session.task_id is set).
invergent-ai · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add invergent-ai/surogates --skill subagent-task-worker技能说明
name: subagent-task-worker description: "Pitfalls, examples, and edge cases for workers executing a Surogates subagent task. Loaded automatically when the dispatcher spawns a session bound to a Task (Session.task_id is set)." version: 1.0.0 license: MIT
Subagent Task Worker — Pitfalls and Examples
You're seeing this skill because the dispatcher spawned you for a subagent task — your
Session.task_idis set and the harness has exposed theworker_complete,worker_block, andworker_contextself-tools to you. This skill is the deeper detail beyond the system-prompt basics: good handoff shapes, retry diagnostics, edge cases, and what NOT to do.
See Tasks (Subagent Task Layer) for the conceptual chapter and Tools for the parameter tables.
What you have access to
You're running for a Task. Three self-tools are available only to you, gated by Session.task_id:
| Tool | Use it when |
|---|---|
worker_context | At the start of your run, especially on retry. Returns goal, accumulated context (from prior unblocks), parent task results, and prior attempt summaries. |
worker_complete | When you've actually finished. Writes the explicit summary + structured metadata to the task row; the parent agent sees this in its worker.complete event. |
worker_block | When you need new context that isn't available without a human or peer providing it. Does NOT consume a retry attempt. |
You also have the same tool surface a spawn_worker child would have: read/write files, web, terminal, etc. -- subject to the AgentDef filter pinned to this attempt.
Step 0 — Orient yourself
The first thing you should do on a non-trivial task is worker_context. It tells you:
- The original
goal. - Any
contextaccumulated from prior unblocks (timestamped). attempt_count-- if > 1, you are a retry. Read theprior_attemptslist before doing anything.parents-- if non-empty, each entry'sresultandresult_metadatais the upstream work you're building on. Don't re-derive it.
Your initial USER_MESSAGE already includes a short summary of prior attempts (when attempt_count > 1), bounded to the last 5. worker_context is how you read the full detail.
Good summary + metadata shapes
worker_complete(summary, metadata) is how downstream readers (the parent agent, future retries, humans) understand what you did. Aim for summary to be 1-3 sentences a human can scan; metadata to be machine-readable facts.
Coding task:
worker_complete(
summary="shipped rate limiter — token bucket keyed on user_id with IP fallback; 14 tests pass",
metadata={
"changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
"tests_run": 14,
"tests_passed": 14,
"decisions": ["user_id primary; IP fallback for unauthenticated requests"],
},
)
Coding task that needs human review:
For most code-changing work, "done" should mean "human reviewed and approved." Use worker_block instead of worker_complete, with a reason that starts review-required:. Leave the structured info (diff path, test counts, what to look at) for the parent agent or human to discover via worker_context.
# (NOT worker_complete — block instead so a reviewer steps in)
worker_block(
reason=(
"review-required: rate limiter shipped, 14/14 tests pass — "
"needs eyes on the user_id-vs-IP fallback choice before merge"
),
)
A reviewer (human, or another task spawned by the orchestrator) then calls unblock_task to resume you, OR cancel_task if a fresh attempt is wanted.
Research task:
worker_complete(
summary="3 inference servers reviewed; vLLM wins on throughput, SGLang on latency, TRT-LLM on memory",
metadata={
"sources_read": 12,
"recommendation": "vLLM",
"benchmarks": {"vllm": 1.0, "sglang": 0.87, "trtllm": 0.72},
},
)
Review task:
worker_complete(
summary="reviewed PR #123; 2 blocking issues: SQL injection in /search, missing CSRF on /settings",
metadata={
"pr_number": 123,
"findings": [
{"severity": "critical", "file": "api/search.py", "line": 42, "issue": "raw SQL concat"},
{"severity": "high", "file": "api/settings.py", "issue": "missing CSRF middleware"},
],
"approved": False,
},
)
Shape metadata so downstream parsers (the parent orchestrator, an aggregator task, a reviewer skill) can use it without re-reading your prose.
The coordination board — share as you work
Because you were spawned into a fan-out, you also have share_note, read_board, and expand_note: a shared, verified board that all sibling workers, retries, and the coordinator read. This is how your discoveries help peers while they work, instead of only at handoff time.
When to write (batch related notes into one share_note call):
- FAIL — highest value, post immediately. You tried something and it dead-ended: name what you ran and the observed error. A sibling is one note away from repeating it.
- FACT for reusable knowledge anchored to specifics (path, symbol, endpoint, error class). Not narration — anchors a peer can act on.
- CLAIM before starting a substantial unit of work that a sibling might also pick ("claiming the slack adapter"). Expires automatically; re-post to renew.
- RESULT when you have a candidate outcome, as
outcome=…|evidence=…|risk=…where the evidence names a check you ACTUALLY ran and what it printed. Your latest RESULT replaces your previous one.
When to read: [Board update] messages arrive in your history automatically as peers post. Additionally call read_board at decision points — before committing to an approach, and before retrying anything that smells like a known dead end — because inline updates may be stale (superseded results, expired claims).
Note
阅读完整来源 ↗