101 lines
3.5 KiB
Markdown
101 lines
3.5 KiB
Markdown
---
|
|
name: subagent-registry
|
|
description: 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
|
|
|
|
```json
|
|
{
|
|
"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 '<name>' (<id-short>) using <provider>"
|
|
|
|
### 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 '<name>'. Available: <list-of-names>"
|
|
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 '<name>' (<id-short>) — <provider> 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 '<name>'"
|
|
|
|
### 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 <N> subagents from session '<name>'"
|
|
|
|
## 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"
|
|
```
|