# Writing a role

> A name, a sentence about when to use it, an agent, a model, an effort — written once, so you stop describing the same colleague every morning.

A role is a job you have written down, so that "get the reviewer on this" is a
thing you can say.

You do not need one to start. A lead agent can be told in a sentence — *have
Codex write the tests* — and it will hand the piece over on the agent and model
you named. Roles are for the two or three you find yourself asking for every
day, and for the ones you would rather the lead chose *without* being asked.

They live in **settings → crew**. A machine starts with none, because what a
good reviewer is depends on the code.

![settings → crew — the roles on this machine, each with its CLI and model](https://beafk.app/docs-shots/crew.webp)

## The fields

**Name** — `builder`, `reviewer`, `scout`. This is what the lead agent asks for,
so make it obvious.

**Summary** — one line saying what this role does.

**When to use it** — the sentence that actually does the work. The lead agent is
handed your roles as a list of routing rules, and this is the rule. "When a
change touches the database schema" gets picked at the right moment; "for
reviews" gets picked always or never.

**CLI** — which agent runs it.

**Model** and **effort** — what that agent runs on. A scout that reads a lot and
decides little can be cheap and fast. A reviewer that has to be right should
not be.

**The page itself** — everything under the fields is for you and for whoever
edits this role next: why it exists, what good looks like, what it got wrong
last time.

> [!IMPORTANT]
> What reaches the agent doing the work is the **name, the summary, when to use
> it, and the CLI, model and effort** — plus the brief the lead agent writes at
> the moment it hands the piece over. The body of the page is not sent, and it
> is not a system prompt.
>
> So a rule you need every run to obey belongs in a [skill](https://beafk.app/docs/skills.md), which
> every agent on this machine can read, and not in the body of a role.

## Project or machine

A role can belong to **this project** or to **the whole machine**.

Project roles are the ones whose *when* is about this codebase. Machine roles
are the general ones you want everywhere: a proofreader, a security reader, a
cheap scout.

A project role with the same name as a machine one wins in that project.

## Turning one off

Each role has a switch. Off means the lead agent is not offered it. Useful for a
role you are still writing, or one that is right for a season of work and not
for this one.

## A good starting set

**scout**, **builder**, **reviewer** — three roles get most of the value, and
[what a crew is](https://beafk.app/docs/what-a-crew-is.md) says why those three and why the reviewer
is deliberately a different maker's agent. What to put in the fields:

1. **scout** — a small, fast model, low effort. It reads a lot and writes
   nothing, so it should be the cheapest thing you have.
2. **builder** — your best model, at enough effort to be careful.
3. **reviewer** — a different CLI from the builder, at high effort.

Add whatever your work actually has in it: a front-end hand on the agent whose
components you like, a proofreader for release notes, somebody who only reads
logs. Nothing here is limited to writing code.

Three roles whose *when* sentences do not overlap beat ten that do. The lead
agent is choosing from a list, and two rules that could both apply give it no
way to choose right.

## Writing them with an agent

You do not have to fill in a form. The crew screen has a chat of its own: say
what you want the role to be and let it write the page, then read it. That is
usually faster than typing one on a phone, and produces a better *when*.

---

beafk documentation · Crew · https://beafk.app/docs/writing-a-role

In this section:
- What a crew is — https://beafk.app/docs/what-a-crew-is.md
- Writing a role — https://beafk.app/docs/writing-a-role.md (this page)
- Watching a crew — https://beafk.app/docs/watching-a-crew.md

Every page, one line each: https://beafk.app/docs/llms.txt
All of it in one file: https://beafk.app/docs/llms-full.txt