Verboo Code: how to create a subagent with /agents

You ask Verboo Code to review a PR and, in the middle of the conversation about your feature, the coding agent fills the context with 40 files it just read. A subagent fixes that: it runs the task in its own context, with the tools you allowed and the instructions you wrote, and hands only the result back to the main conversation. In this tutorial you create one, from the file to actually using it.

What is a subagent in Verboo Code?

It is a specialized agent that the main session calls through the Agent tool. Each subagent is a Markdown file: the frontmatter sets its name, when to use it and which tools it has; the body of the file becomes its system prompt.

Verboo Code ships with a few built in, such as general-purpose and statusline-setup. Yours join the same list.

How do I create a subagent with /agents?

Inside the session:

/agents

This opens the agents menu, with the built-in ones and yours. To create a new one, the wizard asks:

1. Where to save it: Project (.verboo/agents/), which goes into the repository, or Personal (~/.verboo/agents), which applies to you in every project.
2. How to create it: generate it from your own description (the option marked recommended) or Manual configuration.
3. Then: tools, model, color and memory.

At the end, /agents writes a .md file to the folder you picked. You can write that same file by hand, which is what the next section shows.

How do I write the subagent file by hand?

mkdir -p .verboo/agents

And the file .verboo/agents/revisor.md, a reviewer that only reads and never edits:

---
name: revisor
description: Reviews the current diff looking for bugs, missing tests and broken contracts. Use proactively after any change in src/.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. Do not edit any file.

1. Run git diff to see what changed.
2. For each changed file, look for: logic bugs, untested edge cases, public signature changes.
3. Reply with a short list, from the most severe problem to the least, with file and line.
4. If you find nothing, say so in one line.

Run /agents again and revisor shows up in the list. If you created the file with the session open and it did not show up, start a new session.

Which fields does the frontmatter accept?

Field	What it does	If you leave it out
name	Subagent identifier	File ignored
description	When to use it. This is what the main agent reads to decide whether to delegate	Error, does not load
tools	Comma separated list, e.g. Read, Grep, Glob, Bash	Every tool in the session
disallowedTools	Tools blocked even if the list allows them	Nothing blocked
model	inherit or one of the menu aliases (sonnet, opus, haiku)	inherit: same model as the conversation
effort	Reasoning level for the subagent	Session default
permissionMode	Its own permission mode	Session mode
maxTurns	Turn limit before it stops (positive integer)	No limit of its own
memory	Persistent memory: user, project or local	No memory
background	true makes it always run in the background	Runs in the foreground
isolation	worktree runs it in an isolated git worktree	Runs in the current folder
color	Subagent color in the interface	No color

Watch out with tools: leaving the field out allows everything, but writing an empty tools: leaves the subagent with no tools at all. And if you turn on memory together with a tools list, Verboo Code adds Read, Write and Edit by itself, because the subagent needs them to read and write its own memory.

How do I get Verboo Code to use the subagent?

Two ways. The direct one is to ask for it by name:

use the revisor subagent on what I changed today

The main agent calls the Agent tool with revisor, which reads the diff in its own context and returns only the list of problems.

The other is to let the main agent decide. It picks by description, so the description has to say when to use it, not just the role. "Code reviewer" is vague. "Use proactively after any change in src/" is a trigger: the Agent tool prompt tells the model to use it without you asking when the description says the subagent should be used proactively.

Where does Verboo Code look for subagents?

Folder	Scope
~/.verboo/agents/	Yours, in every project
.verboo/agents/ or .claude/agents/	The project's. Applies from the current folder up to the root of the git repository

Subagents you already had in the project's .claude/agents/ work without copying. The user folder is only ~/.verboo/agents/; if you changed the config location with VERBOO_CONFIG_DIR, it becomes $VERBOO_CONFIG_DIR/agents/.

Same name in two places? The more specific one wins, in this increasing order: built-in, plugin, yours, project, the --agents flag and, last, the one managed by your company. A general-purpose.md in the project replaces the built-in one for everyone working in it.

Can I define a subagent for a single run?

Yes, with the --agents flag, which takes JSON. Handy in scripts and CI, with no file to create:

verboo --agents '{"revisor": {"description": "Reviews the current diff", "prompt": "You are a code reviewer. Do not edit files.", "tools": ["Read", "Grep", "Glob", "Bash"]}}'

In the JSON, description and prompt are required, and tools is a list. The subagent only exists in that session. The --agent <name> flag, singular, is something else: it picks the agent for the main session itself.

Subagent, skill or AGENTS.md: which one?

	Subagent	Skill	AGENTS.md
Context	Its own, separate from the conversation	The conversation's	The conversation's
Tools	Only the ones you list	The session's	The session's
Good for	Tasks that read a lot and return little: review, search, triage	A repeatable procedure you call by name	Permanent project rules

If the task needs what is already in the conversation, use a skill. If it is a rule that always applies, it goes in AGENTS.md, as in the tutorial on permanent instructions with /memory. A subagent is for keeping heavy work out of the main context, which pairs well with watching that space through /context.

Behavior verified in the Verboo Code source (verbeux-ai/code, v0.15.41) on 2026-11-05: src/commands/agents, src/tools/AgentTool/loadAgentsDir.ts, src/tools/AgentTool/prompt.ts, src/components/agents, src/utils/model/agent.ts, src/utils/markdownConfigLoader.ts and src/main.tsx.