# Agent definitions

[Documentation index](../README.md)

Agent definitions are Markdown files containing strict frontmatter plus an
optional prompt body.

This guide covers normal creation and selection. For the complete field contract,
see the [agent-definition schema](../reference/agent-definition-schema.md).

## Sources

Bundled definitions live in:

```text
dist/agent-definitions/
```

Global definitions live by default in:

```text
~/.pi/agent/agents/
```

When Pi uses a custom agent directory, the global definitions live under that
agent directory's `agents/` subdirectory.

A global definition whose `name` matches a bundled definition is an override.
An unmatched global definition is standalone.

## Enable or disable a definition

Definitions are enabled by default. Set `enabled: false` in a matching global
override to make an extension-provided role unavailable without copying the
bundled definition:

```markdown
---
name: reviewer
enabled: false
---
```

The root effective roster and `/subagents agents` output keep disabled rows and
show their disabled status so the source can be re-enabled. A managed parent
does not receive disabled children in its definition list. A parent referencing
a disabled child can remain discoverable, but is rejected during assignment or
fresh worker startup with an explicit disabled-child reason rather than silently
dropping that child.

Fresh assignments and non-live historical-session restores reject disabled
definitions with an actionable error. A worker that is already live keeps its
launch-time configuration and remains controllable and reusable after its
definition is disabled.

## Bundled roster

### `implementer`

Focused source-edit worker for an explicitly approved implementation.

### `researcher`

Focused current/external research worker. Read-only local policy.

### `reviewer`

Independent read-only reviewer.

### `scout`

Fast read-only codebase reconnaissance.

### `worker`

General-purpose scoped execution worker.

The bundled definitions intentionally use portable Pi-native capabilities.
Local extensions, skills, specialized tools, and personal behavior belong in
global definitions.

## Create a standalone definition

Create a Markdown file in the global agents directory:

```markdown
---
name: docs-reviewer
description: Read-only documentation reviewer
model: openai-codex/gpt-5.6-luna
thinking: medium
systemPromptMode: replace
noSkills: true
noExtensions: true
tools: ["read", "bash"]
---

Review documentation for correctness, navigation, duplication, and broken
examples. Do not edit files.
```

The `name` is authoritative; the filename itself is not the public definition
name.

## Allow direct children

```markdown
---
name: coordinator
tools: ["read", "bash"]
subagents: ["scout", "researcher"]
---

Coordinate the assigned analysis and integrate child results.
```

The effective roster is validated atomically. Every `subagents` name must exist.
Bundled role descriptions and bodies describe role behavior only; orchestration
guidance comes from the active controller contract.

With a non-empty explicit `tools` allowlist, `subagent` is inferred unless
explicitly denied. See [Delegation](../concepts/delegation.md).

## Add body files

A body line that consists only of one supported reference includes that file:

```markdown
---
name: docs-reviewer
---

Use the following additional policy.

@./prompts/docs-policy.md
```

Supported forms:

```text
@./relative.md
@../relative.md
@/absolute/path.md
```

References are resolved from the Markdown file that declares them.

For exact expansion, deduplication, and caller-file precedence, see
[Handoffs and files](handoffs.md).

## Inspect effective definitions

A root supervisor can use:

```text
/subagents agents
```

or the model can use:

```json
{ "action": "list" }
```

Both resolve the same effective roster.

## Override an existing bundled role

Do not copy the complete bundled file just to change one property. Create a
matching partial global definition instead.

See [Customizing bundled agents](customizing-agents.md).

## See also

- [Agent-definition schema](../reference/agent-definition-schema.md)
- [`/subagents` commands](../reference/commands.md)
- [Configuration](../reference/configuration.md)