ryanthedev/oberskills/agent

Dispatching subagents

Guidance for writing Agent tool calls (the Task tool was renamed Agent in v2.1.63; Task(...) still works as an alias). A subagent is a context-isolation tool: it spends tokens in its own window and returns a distilled summary, so your window stays clean. That isolation is also the failure surface — the delegation prompt is the only channel in, and the return summary is the only channel out. Keep both channels precise.

Platform mechanics: references/mechanics.md in this skill directory · Orchestration patterns: references/patterns.md in this skill directory · Verifier dispatch: references/verifier-dispatch.md in this skill directory

Host Mapping

Use the host's available subagent or delegation tool when present. If no such tool is available, work inline and state that the host has no subagent surface.

1. The dispatch gate

Agents cost roughly 4x the tokens of working inline; multi-agent fan-outs cost roughly 15x (Anthropic multi-agent research system). Delegation pays for itself only when isolation or parallelism buys something — multi-agent beat single-agent Opus by 90.2% on breadth-first research precisely because the task decomposed into independent directions. Deciding how to dispatch is itself the first dispatch decision.

Once you've decided to delegate, pick the dispatch mode. Background versus foreground is set by the harness, not by a call parameter (Claude Code mechanics; details in the mechanics reference §7):

Where prompts can't surface — dontAsk mode, or a headless run with no permission handler configured (mechanics reference §7) — pre-grant every permission the task needs; otherwise a delegated edit fails while the subagent reports success.

Spawn-bias drifts across model generations — state trigger conditions in both directions: when a task fans out across independent items, delegate rather than iterating serially; AND when a single read or a sequential edit means just doing it.

2. The delegation contract

The delegation prompt is the only thing the subagent knows about your task. It does not see this conversation, your invoked skills, or files you've read. Thin prompts cause cold-start thrash: the agent re-discovers context you already had. Every dispatch contains four parts (Anthropic's orchestrator finding: without an objective, an output format, tool guidance, and clear boundaries, agents duplicate work and leave gaps):

OBJECTIVE   — the outcome, plus how you will use the result.
              "Find where user auth is implemented; I need the pattern to
              add OAuth" not "search for auth files".
OUTPUT      — the exact deliverable shape AND a size bound.
              "Return only the failing tests with their error messages" not
              "report the test run". Default bound: a distilled summary,
              roughly 1,000–2,000 tokens, no transcripts or file dumps.
TOOLS       — which tools/sources to use and which to skip; rate-limit notes
              (e.g. "arXiv calls sequential; S2/OpenAlex parallel").
BOUNDARIES  — what's in scope vs out; exact paths, branches, identifiers;
              write scope if any.

Add a CONTEXT block when the agent needs state from this conversation:

• Decisions already made (so it doesn't relitigate them).
• What was already tried and failed (so it doesn't repeat it).
• For multi-dispatch chains, the goal anchor: ORIGINAL GOAL / COMPLETED SO FAR / CURRENT SUBTASK / REMAINING PLAN — agents drift off-goal within 10–15 steps without it (ReCAP).
• Any CLAUDE.md rule the task depends on (e.g. "ignore vendor/") when dispatching Explore or Plan — those two built-ins skip CLAUDE.md and git status.

Subagents don't inherit your skills. A fresh subagent has zero awareness of skills you've used. Load them explicitly, as flat lines at the top of the prompt — agents execute flat Skill(...) / Read(...) lines but skip nested directives like "follow every instruction in that file". Resolve all paths yourself before dispatch:

Skill(oberskills:write)
Read(/abs/path/to/reference.md)

For a reusable agent definition (a file in agents/), prefer the skills: frontmatter field, which preloads full skill content at startup.

Write the objective as an outcome, not actions:

If the objective can't be stated as an outcome because the user's own intent is ambiguous, run oberskills:clarify before dispatching. Length is fine; vagueness is not. For a long or novel brief — a new reusable agent definition, or instructions beyond a screen — invoke Skill(oberskills:prompt) for wording-level craft first.

3. Model and effort

Two levers, in order: drop effort before dropping a model tier. Lower effort on the same model is the cheap knob — Anthropic's effort table names subagents as the typical low use — and a weaker model running longer is not a substitute for a stronger one (a model upgrade beat doubling the token budget in Anthropic's testing). Don't compensate for a too-weak subagent by letting it run more.

Where each lever binds (Claude Code). The Agent call takes model but has no effort parameter: a subagent's effort comes from its definition's effort frontmatter, otherwise from your session. For an ad-hoc dispatch to a built-in type, tier and the scope of the brief are the only per-call levers, and the subagent runs at your session's effort. A worker role you dispatch repeatedly earns a definition file with effort pinned (field table: mechanics reference §3); in an API harness you own, set effort per request.

Effort semantics: low buys terse, direct execution with fewer tool calls; medium buys deliberation over alternatives; high+ buys extended reasoning on ambiguity. Defaults by role: low for bounded workers, medium for analysis and synthesis, high or above only for deciders. Effort steers thinking and tool-call volume, not prose length — a return that runs long needs a size bound in OUTPUT (§2), not lower effort. Level names don't buy the same amount of thinking on different models, and Anthropic's guidance on every recent release is to re-run an effort sweep rather than port settings, so treat these role defaults as starting points, not constants. At xhigh/max, leave room in max_tokens: thinking and response text share that cap (number in the snapshot). Behavioral deltas that follow from effort choices: the prompt skill's claude-models.md §5.

Orchestrator default: start one tier below the top, escalate on measured failure. Anthropic's model-selection guidance starts most work one tier below the top and moves to the top model for demanding long-horizon work, or when evals at raised effort still fall short. That is this section's ladder — effort first, then tier — applied to the orchestrator. Ratios price tokens, not tasks: a model can write longer responses, longer files, and more narration for the same job (the snapshot names which), so a flat per-token price can still mean a higher bill. The lever is a length bound in the contract and a conciseness instruction (the prompt skill's snippets.md #22), not effort.

Routing defaults: research/lookup → general-purpose with model: "haiku" (built-in Explore now inherits your model, so it is no longer cheap by construction — mechanics reference §2); extract/analyze worker → sonnet, from a definition with effort: low|medium when the role recurs; write/decide → inherit. When several sources set a subagent's model, the per-call model wins — except on a fork, which ignores it and always runs on your model. Full resolution order: mechanics reference §1.

Lineup snapshot — verified 2026-09-21

The guidance above reads correctly without this block; at the next model release, edit here. Aliases resolve to the latest model in each tier (claude --help: "an alias for the latest model"), so a dispatch written today follows the next upgrade. Sources, all fetched on that date: Anthropic's pricing page, models overview, choosing-a-model guide, effort page, and the Opus 5 and Fable 5.1 prompting pages.