---
name: subagent-manager
description: Create, inspect, update, and remove persistent local A2A sub-agents. Use when the user wants Boardware Genius to manage sub-agents with their own workspace under ~/.nanobot/workspace/agents/<id>_agent, their own AGENTS.json and AGENTS.md, and local A2A visibility in the agent list.
---

# Subagent Manager

Use this skill when the user wants to create or manage a persistent local sub-agent.

## Required Rules

- Persistent sub-agents must be created and updated only through `subagentctl.py` or `/api/subagents`.
- Treat `~/.nanobot/workspace/agents/<id>_agent/AGENTS.json` as the source of truth.
- Do not create a sub-agent by manually editing `workspace/agents/registry.json`.
- Do not create ad-hoc layouts such as `workspace/agents/<id>/agent.json`, `main.py`, or `README.md` as a substitute for a persistent sub-agent.
- Do not write `protocol: "local"` registry records for persistent sub-agents. A valid persistent sub-agent is registered automatically as local A2A with `protocol: "a2a"`.
- Prefer the bundled script over hand-editing JSON files, because the script keeps `AGENTS.json`, `AGENTS.md`, and the registry entry consistent.

## Workflow

1. Inspect the current sub-agents first:
   `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py list`
2. Create or update the sub-agent with:
   `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py create ...`
3. Verify the generated workspace:
   `~/.nanobot/workspace/agents/<id>_agent/`
4. Verify the agent registry entry exists by checking `/api/agents` or `workspace/agents/registry.json`.
5. If the user wants custom skills, edit files under:
   `~/.nanobot/workspace/agents/<id>_agent/skills/`

## Creation Standard

When the user asks for a new specialized sub-agent, always:

1. Choose a stable kebab-case id.
2. Create it with `subagentctl.py create` or `POST /api/subagents`.
3. Confirm the generated workspace is `~/.nanobot/workspace/agents/<id>_agent/`.
4. Confirm `AGENTS.json` exists in that directory.
5. Confirm the unified agent list shows the same id as a managed sub-agent entry.

If the user asks for "an agent for X", interpret that as a persistent sub-agent when they want a reusable local worker with its own prompt, memory, skills, or MCP setup.

## Repair Standard

If you find a malformed "sub-agent" created through the wrong path, repair it instead of reusing the broken layout:

1. Read any existing metadata that is useful, such as id, name, description, prompt, tags, aliases, or MCP config.
2. Recreate the agent through `subagentctl.py create` or `/api/subagents`.
3. Verify the new canonical directory `~/.nanobot/workspace/agents/<id>_agent/AGENTS.json`.
4. Remove the malformed directory or stale registry entry only after the canonical sub-agent exists.

Malformed examples include:

- `workspace/agents/<id>/agent.json`
- registry entries with `protocol: "local"`
- agent folders that do not contain `AGENTS.json`

## Commands

- Create:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py create --id research-agent --name "Research Agent" --description "Research-focused local A2A sub-agent" --system-prompt "Focus on research tasks and be concise."`
- Show:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py show research-agent`
- Delete:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py delete research-agent`
- Set system prompt:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py set-system-prompt research-agent --text "New prompt"`
- Add HTTP MCP:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py add-mcp-http research-agent --server-id docs --url http://127.0.0.1:9000/mcp`
- Add stdio MCP:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py add-mcp-stdio research-agent --server-id localtools --command npx --arg -y --arg @modelcontextprotocol/server-filesystem`
- Remove MCP:
  `uv run python nanobot/skills/subagent-manager/scripts/subagentctl.py remove-mcp research-agent --server-id docs`

## Notes

- `AGENTS.json` is the machine-readable source of truth for the sub-agent.
- `AGENTS.md` is regenerated from `AGENTS.json` when the script updates the sub-agent.
- Builtin skills remain available automatically. Workspace-specific skills live under the sub-agent workspace `skills/` directory.
- This MVP exposes the sub-agent through local A2A `message/send` only.
- New sub-agents default to `delegation_mode="remote_a2a_only"`: they can delegate outward only to remote A2A agents, not to local fallback or plugin agents.
- A valid persistent sub-agent should appear in both `/api/subagents` and `/api/agents`.