using-pi-subagents

Using Pi Subagents

Use this skill when deciding whether or how to delegate with the subagent_* tools.

Prefer direct work

Only use a subagent when the work can be split into independent tasks, or when context isolation provides a concrete benefit.

Otherwise, do the work directly.

Keep planning, critical-path work, integration, deterministic checks, authorization decisions, and the final answer in the main agent.

Do the work directly when it is simple, latency-sensitive, tightly coupled to the current context, likely to need user clarification, or faster than preparing and verifying a delegation.

Nested subagents are unsupported.

Spawn one least-privilege job

Use subagent_spawn for one subagent job.

The task defines the child's specialization, objective, constraints, and expected result.

The selected tools define what the child can do.

Select only from read, bash, powershell, edit, write, grep, find, ls, and codemode.

Omit tools for the read-only default of read, grep, find, and ls.

Pass an explicit empty list when the child needs no work tools.

Add only the smallest sufficient tool set for the task.

Select codemode explicitly when the child needs scripted tool calls, parallel calls, or output filtering.

Select the tools that scripts need separately; codemode does not enable automatic extension or MCP discovery.

Treat codemode classifier and image model calls as provider requests that can disclose data and incur costs.

Treat bash and powershell as unrestricted command execution that can also modify the workspace.

Treat edit and write as explicit workspace mutation capabilities.

The runtime always adds subagent_send and child subagent_wait for communication.

Attach skills only when the child needs reusable instructions that should remain available through Pi's progressive disclosure.

Each attached skill path must be a local Markdown skill file or a directory containing at least one skill Pi can load, with skill names unique across all attachments. Every declared skill discovered within a directory must load successfully; one valid skill does not make a partially invalid directory acceptable.