Create reusable persona files that shape a subagent's role, focus, and tool access. Define what a subagent looks for, how it formats its output, and what it is not allowed to do.

Agent personas are markdown files that configure the role and behavior of a spawned subagent. Where a custom mode shapes how the main task works, a persona shapes how a helper subagent works. It controls the subagent's identity, checklist, output format, and constraints.

How personas work

When Bob spawns a subagent, it checks .bob/agents/ for a persona file whose description matches the task. If one is found, the persona is loaded as the subagent's mode: the role body is injected into the subagent's system prompt and layers on top of its base instructions.

Personas are not loaded automatically into the main conversation. They only take effect when a subagent is spawned, either by Bob on its own initiative or when you ask Bob to delegate a specific task.

Persona file format

Persona files use YAML front matter followed by a free-form role body:

---
name: code-reviewer
description: Reviews code for correctness, readability, and maintainability. Read-only.
tools:
  - read
---

You are a senior software engineer conducting a structured code review.

Review each file against this checklist:
1. Correctness: logic errors, missing null checks, unhandled edge cases
2. Readability: long methods, deep nesting, unclear naming
3. Maintainability: tight coupling, missing abstraction, duplicated logic

Report findings in a table with columns: Severity, File, Lines, Description.
Use severity levels: HIGH, MEDIUM, LOW.

Do not suggest fixes. Describe issues only.

Front matter fields

Field	Required	Type	Purpose
`name`	Yes	string	Identifier used in logs. Should match the filename without `.md`.
`description`	Yes	string	Bob uses this to match the persona to a task. Write it as a one-line mission statement.
`tools`	No	list	Constrains which tool groups the subagent can use. Omit to inherit defaults.

Tool groups

The tools field accepts the same groups as custom modes: read, edit, command, browser, mcp.

For read-only personas such as reviewers, planners, and summarizers, set tools: [read] to prevent accidental edits.

The tools field is a ceiling, not a grant. Setting tools: [edit] on a persona has no effect if the active task does not have Edit permissions enabled. A persona can only restrict tool access, never expand it beyond what the task allows.

File placement

Location	Scope	Use case
`<project>/.bob/agents/`	This project only	Team-shared personas committed to the repo
`~/.bob/agents/`	All projects on this machine	Personal personas that apply across repos

If both locations contain a persona with the same name, the project-level file takes precedence.

Your .bob/ directory can hold personas alongside your other configuration:

code-reviewer.md

pr-summariser.md

custom_modes.yaml

Creating your first persona

Create the agents directory in your project root:

mkdir -p .bob/agents

Create a persona file. The filename (without .md) should match the name field in the front matter.

touch .bob/agents/code-reviewer.md

Add front matter and a role body. See Persona file format above for the structure.

Commit the file to your repository so your team shares the same personas.

Example personas

code-reviewer.md

Reviews source files for correctness, readability, and maintainability. Produces a severity-ranked findings table and does not suggest fixes.

---
name: code-reviewer
description: Reviews code for correctness, readability, and maintainability. Read-only.
tools:
  - read
---

You are a senior software engineer conducting a structured code review.

Review each file against this checklist:
1. Correctness: logic errors, missing null checks, unhandled edge cases
2. Readability: long methods, deep nesting, unclear naming
3. Maintainability: tight coupling, missing abstraction, duplicated logic

Report findings in a table with columns: Severity, File, Lines, Description.
Use severity levels: HIGH, MEDIUM, LOW.

Do not suggest fixes. Describe issues only.
If a file has no findings, list it explicitly as clean.

pr-summarizer.md

Reads a set of changed files and produces a structured pull request description covering what changed, the likely intent, and any areas the reviewer should pay attention to.

---
name: pr-summarizer
description: Reads changed files and produces a structured pull request description. Read-only.
tools:
  - read
---

You are a developer writing a pull request description for a teammate.

Read the provided files and produce a PR description with these sections:

**Summary**: One or two sentences describing what this change does.
**Why**: The likely motivation, inferred from the code changes.
**What changed**: A bullet list of the key changes, grouped by area if there are several.
**Reviewer notes**: Anything the reviewer should pay particular attention to, including edge cases, intentional trade-offs, or areas of uncertainty.

Write in plain, direct language. Do not pad the description.
Do not list every file changed. Focus on what matters to the reviewer.

Using a persona

Reference a persona by name when asking Bob to delegate a task:

Use the code-reviewer persona to review the files in src/auth/.

Spawn a subagent using the pr-summarizer persona.
Read the changed files and produce a PR description.

Bob will load the matching persona from .bob/agents/ and apply it to the spawned subagent.

Inline personas

For a one-off task, you can describe the role directly in your prompt without creating a file:

Spawn an Explore subagent with this role:
You are a naming auditor. Read all files under src/ and flag variable and
function names that use abbreviations or are misleading. Return a table:
File, Line, Current Name, Issue.

Inline roles work just as well as file-based personas for a single task. Persona files are worth creating when you want to reuse the same role across multiple tasks or share it with your team.

Passing conversation history

By default, a subagent only receives the task description. It does not see your prior conversation turns. This keeps its context small and focused.

When a subagent needs to honor decisions or constraints from earlier in the conversation, phrase your prompt to reference prior context:

Use the code-reviewer persona to review src/payments/.
Take into account what we discussed about the error handling approach.

Bob infers fork_context: true from phrases like "what we discussed" or "our earlier decision", and passes the conversation history into the subagent.

Note:

Passing conversation history copies your entire conversation into the subagent's context window. On a long conversation this adds meaningful token cost. Prefer the default (no forked context) unless the subagent genuinely needs prior context to do its job.

Personas, modes, and rules

Mechanism	Scope	What it controls	When to use
Mode	Entire task	Tool ceiling and role definition for the main task	When the main agent needs a different posture, such as read-only, docs-writer, or security reviewer
Rule	Task or mode	Standing instructions loaded into the system prompt	Team conventions, formatting standards, guardrails that apply every time
Persona	One subagent	Role, focus, output format, and tool constraints for a spawned subagent	When a helper needs domain focus: reviewing code, summarizing changes, planning tests

Agent personas

On this page