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

name, description

name	description
subagent-registry	Manage named subagent instances with persistent provider pinning and memory. Use when spawning, resuming, listing, or deleting subagents.

Subagent Registry

Manage named subagent instances. Each agent gets a human-readable name, persistent memory, and pinned provider for KV cache continuity.

Registry File

<project>/.pi/subagents.json:

{
  "session": "<session-name>",
  "agents": [
    {
      "name": "<human-readable-name>",
      "id": "<agent-uuid>",
      "type": "<agent-type>",
      "provider": "<provider-config>",
      "status": "running|completed|error",
      "created": "<ISO-timestamp>"
    }
  ]
}

Rules

1. Always ask for a name when spawning a new subagent. Never auto-generate. Ask: "What should I name this subagent?"
2. One agent per name. If name exists, ask for a different name.
3. Store the agent ID in the registry immediately after spawn.
4. Use the same provider when resuming — read from registry.
5. Each named agent gets its own memory directory via memory: project in agent frontmatter.
6. No auto-cleanup. Agents persist until explicitly deleted.
7. Session-scoped. Registry is per-project directory.

Workflow: Spawn

1. User requests a subagent
2. Ask for a name if not provided: "What should I name this subagent?"
3. Call Agent({ subagent_type, prompt, run_in_background: true, ... })
4. Wait for completion notification with agent ID
5. Append to .pi/subagents.json:

   {
     "name": "<user-given-name>",
     "id": "<agent-uuid>",
     "type": "<subagent_type>",
     "provider": "<provider-config-from-agent-frontmatter>",
     "status": "running",
     "created": "<ISO-timestamp>"
   }
   

6. Inform user: "Created subagent '' () using "

Workflow: Resume

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

Workflow: List

Display all agents in a compact table:

Name              Type         Provider    Status    Created
----              ----         --------    ------    -------
coder-login       coder-pro    DeepInfra   ✓ done    20:00
coder-nav         coder-pro    DeepInfra   ↻ run     20:05
obsidian-edit     obsidian     StreamLake  ✓ done    19:30

Show: name, type, provider (from config), status, created time.

Workflow: Delete

1. User says "delete " or "kill "
2. Read registry, find agent
3. If running: call TaskStop or steer to abort
4. Remove entry from registry
5. Inform user: "Deleted '' ()"

Workflow: Delete Session

1. User says "delete session " or "clear all subagents for "
2. Find all agents where session == <name>
3. Abort any running agents
4. Remove all matching entries from registry
5. Inform user: "Deleted subagents from session ''"

Provider Config Format

Store as string: "only:<provider-slug>"

Examples:

• "only:DeepInfra"
• "only:Baidu"
• "only:StreamLake"
• "only:Moonshot AI"

When resuming, parse and reconstruct the provider field:

"only:DeepInfra" → { "only": ["DeepInfra"] }

Memory

Each named agent should have memory: project in its frontmatter. This gives it a persistent memory directory at .pi/agent-memory/<agent-name>/ that survives across resume calls.

Session Name

The session field in the registry should match the pi session name. If no session name is set, use the project directory name.

Example Interaction

User: "Spawn a coder-pro to fix the login module"
LLM: "What should I name this subagent?"
User: "auth-login"
LLM: *spawns agent, gets ID 7efad0d8-5a78-415*
LLM: "Created subagent 'auth-login' (7efad0d8) using DeepInfra"

User: "What subagents do we have?"
LLM: *reads registry, displays table*
  auth-login    coder-pro  DeepInfra  ✓ done  20:00

User: "Resume auth-login and tell it to add password reset"
LLM: *reads registry, finds ID, resumes with same provider*
LLM: "Resumed 'auth-login' (7efad0d8) — DeepInfra cache warm"