beaver_project/app-instance/backend-old/nanobot/skills/subagent-manager/SKILL.md

name, description

name	description
subagent-manager	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.