Agents

A named profile: system prompt, model, tool allowlist and permission overrides, declared in markdown.

Where they live

The nested path is the id. Both scopes load; on the same id the project wins.

.agents/agents/reviewer.md      → id reviewer
.agents/agents/team/audit.md    → id team/audit
~/.agents/agents/*.md           → user scope

Frontmatter

---
description: Reviews changes read-only
color: cyan
model: 9router/glm-5.2
tools: [read, glob, grep]
permissions: {shell: ask}
---
You are a code reviewer. Report findings with file and line references.

description: Shown by the agent picker. Absent, none.
model: provider/model, both required. Absent, inherit the session's.
tools: Ids the model can see. A tools key that parses to nothing fails closed to none, with a warning.
permissions: allow, ask or deny per tool. deny also removes the tool.
mode: primary, subagent or all: who may launch it.
color: TUI display color, an ink name or #rrggbb. Display only.

Built in

build: The base system prompt. The startup default, always a way back.
plan: Explore and design. edit and write denied, shell still permission-gated.
general: A subagent with a fresh context. Delegation works with zero files.

Built-ins load first, so a file with the same id overrides one without removing it.

Switching

/agent lists loaded agents and switches between them. Switching works mid-session: history is kept and the next turn runs with the new prompt, model and toolset. The body of a file agent replaces the base prompt, and AGENTS.md plus the skills advertisement are still added on top.