Agent definitions

An agent definition is a Markdown file describing a focused sub-agent - its system prompt, and optionally which tools it may use and which model it runs on. You invoke it by name and it runs as a one-shot sub-agent: autonomous, its own context, reports a result back.

---
description: Reviews a diff or a directory for bugs and risky changes
tools: read_file, grep, glob
model: claude-haiku-4-5
---

You are a careful code reviewer. Read the code you are pointed at and report:
- correctness bugs, with the file and line
- risky or surprising changes
- missing test coverage for changed behavior

Be concise. Do not rewrite the code; describe what you would change.

Save that as .polyglot/agents/reviewer.md and:

> @reviewer look at the changes in src/session/

Polyglot shows running agent: reviewer, runs it with only the tools you allowed, streams its work into the transcript, and records the request and the agent’s final answer in the session - so the main model (and --resume) see the exchange.

Where they load from

Path	Scope
<repo>/.polyglot/agents/*.md	This project. Meant to be committed.
~/.polyglot/agents/*.md	Every project.

A project agent overrides a global one with the same name. /agents lists what’s loaded; /status shows the names.

Frontmatter

Key	Required	Meaning
name	no	Invoke name. Defaults to the filename (reviewer.md → reviewer). Lowercase, digits, -, _.
description	recommended	One line, shown in /agents and the @ picker.
tools	no	Comma list or YAML list of tool names the agent may call. Omit to allow every tool the main session has (minus task). Unknown names are ignored.
model	no	Model id or label, matched against models[] like /model <query>. Applies to the @name <task> form; omit to use the active model. (The agent_<name> tool form runs on the sub-agent model or the active model.)

Everything after the frontmatter block is the agent’s system prompt.

Two ways to invoke

• @name <task> as the whole message - the direct form. The task text is everything after the name; @file mentions in it are expanded first. This is the reliable path: it doesn’t depend on the main model choosing to delegate.
• The agent_<name> tool - each definition is also offered to the main model as a tool it can call on its own when it decides a sub-task fits. Only at the top level; a sub-agent never gets these.

Both share the sub-agent machinery - permission gate, spawn and depth bounds, token cost rolling up into /cost.

Turning it off

POLYGLOT_NO_AGENTS=1 (or true) skips loading entirely - @name is then just text.