pi-config/skills/subagent-registry/SKILL.md

name, description

name	description
subagent-registry	Manage named subagent instances. MUST be used when spawning, resuming, listing, or deleting subagents. Read this skill FIRST before any subagent operation.

Subagent Registry — CRITICAL

You MUST manage <project>/.pi/subagents.json for ALL subagent operations. Read the file before any operation. Write the file after any change.

File Location

<cwd>/.pi/subagents.json (where cwd is the current project directory)

File Format

{
  "session": "<pi-session-name-or-project-dir>",
  "agents": [
    {
      "name": "<human-readable-name>",
      "id": "<agent-uuid-from-spawn-notification>",
      "type": "<subagent_type>",
      "provider": "<exact-provider-config-from-agent-frontmatter>",
      "status": "running|completed|error",
      "created": "<ISO-timestamp>"
    }
  ]
}

MANDATORY Operations

SPAWN — Always do this:

1. Ask user for a name if not provided: "What should I name this subagent?"
2. Spawn the agent: Agent({ subagent_type, prompt, run_in_background: true })
3. Wait for completion notification — extract the agent ID from the response
4. Read current .pi/subagents.json
5. Append new agent entry with name, id, type, provider, status="running", timestamp
6. Write updated .pi/subagents.json
7. Tell user: "Created subagent '' () using "

LIST — Always do this:

1. Read .pi/subagents.json
2. If file doesn't exist or agents array is empty: "No subagents found."
3. Display compact table:

Name         Type        Provider    Status    Created
----         ----        --------    ------    -------
searcher     chat-search Google      ↻ run     15:35

4. Show: name, type, provider, status, created time

RESUME — Always do this:

1. Read .pi/subagents.json, find agent by name
2. If not found: "No subagent named ''. Available: "
3. If found: Agent({ subagent_type, resume: "<agent-id>", prompt: "<new-task>", run_in_background: true })
4. Update status to "running" in registry
5. Tell user: "Resumed '' () — cache warm"

DELETE — Always do this:

1. Read .pi/subagents.json, find agent by name
2. If running: steer to abort first
3. Remove entry from registry array
4. Write updated .pi/subagents.json
5. Tell user: "Deleted ''"

DELETE SESSION — Always do this:

1. Read .pi/subagents.json
2. Remove all agents where session matches
3. Write updated .pi/subagents.json
4. Tell user: "Deleted subagents from session ''"

Rules

• NEVER spawn without asking for a name first
• NEVER skip writing to the registry after spawn/resume/delete
• ALWAYS read the registry before listing or resuming
• Provider config must be preserved exactly from the agent's frontmatter (e.g., "only:DeepInfra")
• No auto-cleanup — agents persist until explicitly deleted
• Each named agent gets memory: project in its frontmatter for persistent memory

Example Workflow

User: "Spawn a coder-pro to fix the login module"
You: "What should I name this subagent?"
User: "auth-login"
You: *spawn agent → get ID 7efad0d8-5a78-415*
You: *read .pi/subagents.json → append entry → write file*
You: "Created subagent 'auth-login' (7efad0d8) using DeepInfra"

User: "List my subagents"
You: *read .pi/subagents.json → display table*
  auth-login    coder-pro  DeepInfra  ↻ running  20:00

User: "Resume auth-login and add password reset"
You: *read .pi/subagents.json → find ID → resume*
You: "Resumed 'auth-login' (7efad0d8) — DeepInfra cache warm"