create-subagent

name	create-subagent
description	Creates new pi subagent definition files (.md with YAML frontmatter) in ~/.pi/agent/agents/ (user-global) or .pi/agents/ (project-local). Trigger when the user asks to define a new agent, create a specialist, add a subagent, write an agent file, or set up a delegated worker for a specific task.

Create Subagent

This skill guides you through creating a well-formed pi subagent definition file. Subagents are Markdown files with YAML frontmatter that pi-subagent discovers at startup and injects into the main agent's system prompt.

---

Step 1 — Clarify intent

Before writing anything, gather the following from the user (ask only what isn't already obvious from context):

1. What should this agent do? — its core specialisation.
2. User-global or project-local?
   • User-global → ~/.pi/agent/agents/<name>.md (available in every session)
   • Project-local → .pi/agents/<name>.md (scoped to the current repo; requires user confirmation before pi runs it)
3. Model preference? — leave blank to use Pi's default; specify when a task clearly benefits from a specific model (e.g. a heavy reasoning task → a thinking model; a fast lookup task → a smaller/faster model).
4. Thinking level? — off | minimal | low | medium | high | xhigh. Only set this when you know it matters; otherwise omit and let the model default apply.
5. Tools needed? — choose the minimal set (see reference below). If unsure, leave at defaults (read, bash, edit, write).

---

Step 2 — Choose a name and write the description

Name rules:

• Lowercase, hyphen-separated (e.g. code-reviewer, doc-writer)
• Short and unambiguous — this is the identifier used in tool calls
• Must match exactly when the main agent calls subagent({ agent: "..." })

Description rules:

• One to two sentences maximum
• Describe what the agent is good at, not what it is
• The main agent reads this description to decide which subagent to call — be specific and action-oriented (e.g. "Rewrites code for clarity and performance" is better than "A code expert")

---

Step 4 — Write the system prompt (Markdown body)

The Markdown body below the frontmatter becomes the agent's system prompt. It is appended to Pi's default system prompt, not a replacement.

Good system prompts for subagents:

• State the agent's role clearly in the first sentence
• List any hard constraints (e.g. "never modify files outside the src/ directory")
• Describe the expected output format if it matters (e.g. JSON, diff, prose)
• Keep it concise — the description field already covers "what the agent does"; the body covers how it should behave

---

Step 5 — Write the file

Use the template below, then save to the appropriate location.

---
name: <agent-name>
description: <one or two sentences — what the agent is good at>
model: <provider/model-id>          # omit to use Pi default
thinking: <off|minimal|low|medium|high|xhigh>  # omit to use Pi default
tools: <comma-separated tool list>  # omit for defaults: read,bash,edit,write
---

<System prompt for the agent. Starts here. Be concise.>