Custom Agents

A custom agent is a single .md file that defines an agent Multi can select as the primary agent for a task or delegate to as a subagent. The file’s frontmatter configures the agent, and its body becomes the system prompt.

Where custom agents live

Multi discovers custom agents from two locations:

Project-level: .multi/agents/*.md in your workspace
User-level: ~/.multi/agents/*.md

Each agent is a single .md file placed directly inside one of these folders. Agents are keyed by their name field. If a project-level agent and a user-level agent share the same name, the project-level one wins.

.multi/
  agents/
    code-reviewer.md
    changelog-writer.md

File format

A custom agent file is YAML frontmatter followed by a markdown body:

---
name: my-agent
description: One sentence describing what this agent does.
---

The markdown body is the system prompt for this agent.

The body is the system prompt and is required. An agent with an empty body is rejected.

Frontmatter schema

Field	Required	Default	Notes
`name`	Yes	-	Must match `^[a-z][a-z0-9-]*$` (lowercase, starts with a letter). Cannot collide with a reserved name (see below).
`description`	Yes	-	One sentence. Shown in the agent picker and in the delegation catalog.
`tools`	No	`multi.coder:Read, multi.coder:Glob, multi.coder:Grep`	Comma-separated, fully-qualified registry ids (e.g. `multi.coder:Read`, `multi.core:WebFetch`).
`use`	No	`subagent`	One of `subagent`, `primary`, `both`. See below.
`skills`	No	none	Comma-separated skill names, preloaded into the agent’s prompt.

Reserved names (cannot be used for name): general, generalist-supervisor, generalist, namer, custom-worker, multidoctor.

The `use` field

subagent - the agent can be delegated to by a supervisor.
primary - the agent is selectable as the main agent for a task.
both - the agent can be either.

Tool scoping rules

Tools are the most common source of surprises, so read these carefully:

Custom agents can never be given Delegate or Spawn. These are stripped so custom agents cannot recurse.
A primary agent automatically also gets AskQuestion, UpdateTodoList, and ActivateSkill.
A subagent automatically gets Return, and automatically loses AskQuestion and UpdateTodoList.
Agents may only use tools from multi.core. A tool id in tools that is outside this scope is a hard error at run time.

Examples

Minimal subagent

Only name, description, and a body. Everything else falls back to defaults, so this agent is a subagent under the multi.coder with the Read, Glob, and Grep tools:

---
name: docs-finder
description: Locates and summarizes documentation relevant to a task.
---

You locate documentation and configuration relevant to the current task.
Search the workspace, read the most relevant files, and report concise
findings with file paths. Do not modify anything.

A primary code reviewer

An explicit primary agent with a fully-qualified tools list and a preloaded skill:

---
name: code-reviewer
description: Reviews changed code for correctness, clarity, and security issues.
use: primary
tools: multi.coder:Read, multi.coder:Glob, multi.coder:Grep, multi.core:WebFetch
skills: api-review
---

You are a meticulous code reviewer. Inspect the changes in the workspace and
report issues grouped by severity. Focus on correctness, edge cases, naming,
backward compatibility, and security. Cite exact file paths and line numbers.
Do not make edits - only report findings and suggested fixes.

Troubleshooting

All validation failures are silent - a rejected agent simply never appears in the picker, with no error. Work through this table if an agent is missing:

Cause	Fix
`name` doesn’t match `^[a-z][a-z0-9-]*$`	Use lowercase letters, digits, and hyphens; start with a letter.
`name` collides with a reserved/built-in name	Rename to something not in the reserved list above.
`use` is not `subagent`, `primary`, or `both`	Set `use` to one of those three values (or omit it).
Missing `---` delimiters, or missing `name`/`description`	Add both frontmatter delimiters and both required fields.
Empty markdown body	Add a system prompt below the frontmatter.
File isn’t directly inside `.multi/agents/` or `~/.multi/agents/`, or isn’t a `.md` file	Move the file directly into an agents folder and give it a `.md` extension.

Multi Doctor - the built-in agent that authors and repairs custom agents for you
Skills - reusable guidance you can preload with the skills field
AGENTS.md - project-wide guidance for every agent