# Agent definitions

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

Agent definitions describe an agent's capabilities, not a required
workflow. They 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/
```

Project definitions are optional and live in the current project:

```text
<cwd>/.pi/agents/
```

Pi Herdsman discovers project definitions when Pi considers the project
trusted. Precedence is:

```text
bundled < project < global
```

Global definitions remain final user policy. For example:

```text
.pi/
└── agents/
    └── reviewer.md
```

Project definitions apply only to their project cwd, and the Definitions UI
writes global overrides, never project files.

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

A project or global definition whose `name` matches a lower-precedence
definition overlays it. An unmatched definition is standalone.

`flexible-lead`, `orchestrator-lead`, and `managed-lead` are reserved Lead
definitions. They use the layered definition engine but are not Agents
available through discovery or delegation. The first two configure ordinary
Lead runtime instructions and ordinary tools; `managed-lead` configures launch
policy for Manager-assigned project Leads. They appear first in the flat
Definitions list in that order. The ordinary profiles offer Details only;
`managed-lead` offers Model, Thinking, and Details. See
[Customizing bundled agents](customizing-agents.md#lead-execution-profiles).

### Permission-aware extensions

Agent definitions may include a `permission:` mapping for compatible
permission-aware Pi extensions.

[`pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system)
can consume the same global or trusted project-local agent definition as Pi
Herdsman:

```yaml
---
name: reviewer
tools: ["read", "ls", "find", "grep"]
permission:
  "*": deny
  read: allow
  ls: allow
  find: allow
  grep: allow
---
```

Pi Herdsman accepts and preserves `permission:` but does not evaluate its
contents or make authorization decisions from it. Managed agents publish the
conventional `<active_agent name="<definition>"/>` identity signal and
subagent lineage metadata used by compatible extensions. Herdsman separately
projects current semantic identity and direct-owner context in its
`pi_herdsman_agent` prompt section; this is not an authorization signal.
Permission policy is effective only when the
compatible permission extension is loaded in that Pi session. The permission
extension is optional; Pi Herdsman does not install or depend on it.

## Enable or disable a definition

Definitions are enabled by default. Set `enabled: false` in a matching project
or global overlay to make a definition unavailable without copying the bundled
bundled definition:

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

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

`delegate` and `continue` reject disabled definitions with an
actionable error. An already active agent may finish and remains controllable
according to its current available actions; disabling a definition does not
mutate that assignment.

## Bundled roster

### `implementer`

Focused source-edit agent for an explicitly approved implementation.

### `researcher`

Focused current/external research agent. Read-only local policy. It also
allows the default web tool names exposed by `pi-web-access`:
`web_search`, `fetch_content`, `get_search_content`, and `source_check`.
Web access is optional. Install it with:

```text
pi install npm:pi-web-access
```

Pi Herdsman does not depend on or install `pi-web-access`. Without those tools,
the researcher retains local inspection capabilities and reports unavailable
external evidence. Normal Pi extension discovery is intentionally enabled for
this role so an installed compatible extension can provide the tools. If
`pi-web-access` is configured with different public tool names, replace the
researcher's `tools` array through a matching project or global overlay.
Extension code itself is not sandboxed by the callable-tool allowlist.

### `reviewer`

Independent read-only reviewer.

### `scout`

Fast read-only codebase reconnaissance.

### `generalist`

General-purpose scoped execution agent.

The bundled definitions are portable defaults, not required workflow stages.
Project definitions are for repository-specific policy; global definitions are
for user-specific final policy.

## 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", "ls", "find", "grep"]
---

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

Read-only behavior must be enforced by the effective tool policy, not only by
prompt text. For normal filesystem inspection, explicitly allow `read`, `ls`,
`find`, and `grep`, and omit mutation-capable tools such as `bash`,
`powershell`, `edit`, and `write`. Disable extension discovery when the role
does not need extension-provided capabilities.

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

## Allow direct agents

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

Coordinate the assigned analysis and integrate direct agent results.
```

The effective roster is validated atomically. Every `agents` name must exist.
Bundled role descriptions communicate each role's purpose and selection boundary;
the active controller contract remains authoritative for delegation behavior.

The non-empty `agents` list is required, but is not by itself sufficient, to
enable all nine managed-agent coordination tools. Delegation is disabled when
`excludeTools` contains `agent`, when `noTools: true` unless the explicit
`tools` list contains `agent`, or when `tools` is explicitly empty. Otherwise,
omitted `tools` permits delegation and explicit ordinary tools permit it. Every
managed agent receives mandatory `ask_owner`; a definition launched as a leaf
has its `agents` list removed. The `agent` name in these policy settings is not
a registered or callable tool, and leaf projection also removes it from an
existing `tools` list. Ordinary tool settings cannot remove role-required
coordination tools. When `tools` is omitted, Pi's configured/default tool
selection is preserved; an explicit allowlist is augmented with required role
tools. 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
@~/home-relative.md
```

On Windows, the native backslash forms are also supported, including
`@.\relative.md`, `@..\relative.md`, `@~\home-relative.md`, rooted paths,
drive-rooted paths, and UNC paths. References use the host platform's native
path resolution rules.

References are resolved from the Markdown file that declares them.

The bundled Agent definitions are `generalist`, `implementer`,
`researcher`, `reviewer`, and `scout`. All three reserved Lead definitions are
excluded from this roster. The session-start
agent-definition roster and the `list_agents` result use the same metadata
projection.

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

## Inspect effective definitions

A lead Pi session can use:

```text
/agents definitions
```

or the model can use:

```json
{}
```

Both resolve the same effective roster.

For model-assisted definition management, ask Pi directly or explicitly invoke
`/skill:agent-definitions`. The bundled skill uses the same
project/global Markdown definitions and existing Herdsman validation rather than
a separate configuration interface.

The human `Definitions` menu is a flat list of actionable definitions, with
reserved `flexible-lead`, `orchestrator-lead`, and `managed-lead` first in that
order. Each row identifies its contributing source or
sources as `bundled`, `project`, and/or `global`. Model, thinking, and enabled
settings can be changed through the menu, but edits always write global
overrides. `Inherit current session` removes only that field. Unset model and
thinking fields inherit the spawning controller for fresh delegation, while
continuation restores the saved session's settings. Contextual help updates for
the selected row.

## 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)
- [`/agents` commands](../reference/commands.md)
- [Configuration](../reference/configuration.md)