subagent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Subagent

“Subagent” means a separate `pi` process spawned by the current pi orchestrator.
The orchestrator may delegate edits, implementation, verification, review,
research, or any other bounded task it deems useful.

## Rules

- Delegate the requested task to the subagent instead of doing that task in the
  orchestrator's context.
- Prefer serial delegation: one subagent at a time, each finished before the
  next starts. This keeps the work reviewable and stops children racing on the
  same files. Fanning out is the exception — reserve it for genuinely
  independent pieces where waiting is the real cost, and say why before doing
  it.
- Run the subagent from the directory relevant to the task.
- Use `pi --print --no-session` so the child has isolated context and returns
  its result to the orchestrator.
- Pass a short, simple task as one shell-quoted prompt argument. For a
  multiline, quote-heavy, code-heavy, or synthesized prompt, write the exact
  prompt to a private temporary file outside the repository and redirect that
  file to pi's stdin. Do not squeeze complex prompts into a command argument or
  tell the child to read the prompt file itself.
- Remove temporary prompt files after the child exits, including on failure.
- When the operator explicitly requests or suggests using subagents, get their
  small/medium/big provider, model, and thinking-effort preferences before
  spawning the first child. Ask once per operator request and reuse the answers
  across its tasks and phases.
- If the operator already supplied one provider/model/effort combination, apply
  it to every tier unless they distinguish tiers; do not ask again. Accept “same
  for all” as a complete answer.
- For autonomous delegation that the operator did not request or suggest, use
  any tier preferences already given in the conversation; otherwise inherit pi's
  configured provider/model defaults and choose thinking effort from the task
  tier.
- Pass a selected model as both `--provider <provider>` and `--model <model>`.
  Use the named provider when supplied. Otherwise, use
  `pi --list-models "<model>"` to find a configured provider.
- Pass the selected effort or thinking level with `--thinking <level>`. Omit
  `--provider` and `--model` only when inheriting pi's configured defaults.
- Give the subagent the capabilities needed for its role. Omit `--tools` when it
  may edit, implement, verify, or otherwise use pi's normal tools; use an
  allowlist only when the task must be constrained, such as a read-only review.
- Do not use `eval` when constructing the command.
- Report the subagent's result. If the command fails, report its exit status and
  stderr; do not silently replace it with your own attempt.

## Task Sizing

Classify each delegated task or phase independently and use the smallest tier
likely to complete it reliably. Do not size every child from the overall
request.

- **Small:** bounded lookup, focused verification, simple isolated edit, or a
  known command/test. Default when asking: configured provider/model with `low`
  effort.
- **Medium:** multi-step investigation, implementation within one component, or
  a standard code review. Default when asking: configured provider/model with
  `medium` effort.
- **Big:** architecture or broad research, cross-cutting implementation,
  security/high-risk reasoning, or review of a large change. Default when
  asking: configured provider/model with `high` effort.

For mixed work, split only where phases are genuinely separable, then size each
phase. A large parent task may use a big research/planning child, medium
implementation child, and small verification child. Do not create extra children
merely to exercise every tier.

When tier preferences are required, ask one compact numbered question before
delegation:

```text
Which subagent provider/model/thinking effort should I use?
1. Small — default: configured provider/model, low
2. Medium — default: configured provider/model, medium
3. Big — default: configured provider/model, high
You can answer each tier or say “same for all: <provider>, <model>, <effort>”.
```

## General Usage

Treat caller arguments (`$@`) as the delegated task. Pi supplies skill arguments
as conversation text, not shell positional parameters: substitute them for
`<task>` before running this command through bash; do not pass literal `$@` or
`<task>`.

For a short, simple task:

```bash
pi --print --no-session \
  [--provider <provider> --model <model>] \
  [--thinking <level>] \
  "<task>"
```

Replace or omit the bracketed optional arguments rather than passing literal
brackets. Shell-quote the task as data and preserve it as one prompt argument.

For a complex prompt:

1. Run `mktemp "${TMPDIR:-/tmp}/pi-subagent-prompt.XXXXXX"` and keep the
   returned path.
1. Use the `write` tool to put the exact delegated prompt at that path; do not
   construct it through shell interpolation. The file created by `mktemp` is
   private to the current user.
1. Substitute the returned path for `<prompt-file>` and run:

```bash
prompt_file="<prompt-file>"
trap 'rm -f -- "$prompt_file"' EXIT
pi --print --no-session \
  [--provider <provider> --model <model>] \
  [--thinking <level>] \
  < "$prompt_file"
```

Pi merges piped stdin into its initial prompt. Do not also pass the prompt as an
argument.

From hurricanehrndz/agent-toolkit, MIT.

More from hurricanehrndz/agent-toolkit