Step-by-step guide

Design an agent role

Turn a recurring responsibility into a role the system can understand and constrain.

You will build: A lead that can delegate to two bounded sub-agents.
Time: 15 minutes
Before you start: One model provider declared in settings.json. The examples below use anthropic/..., so a providers entry named anthropic must exist: the token before the first slash has to match a declared provider name, and there are no built-in providers.

What this changes

Start with the job, not the prompt. A strong role makes its responsibility, authority and relationship to other agents clear before the first task begins.

01
A recognizable responsibility
People and other agents can tell when this role is the right one for the work.
02
Deliberate authority
The role has enough capability to succeed without inheriting powers it does not need.
03
Reusable behavior
The same role can return across projects and tasks without being reinvented in every conversation.

Minimum setup

Start with one working configuration.

Begin with one deliberately narrow role. Its filename becomes the agent name; the frontmatter sets its model and authority; the Markdown body defines the job.

~/.clarvis/agents/reviewer.md agent

---
description: Read-only investigator that answers questions about this repository.
model: anthropic/claude-sonnet-4-5
grants:
  - read_workspace
iteration_limit: 20
---

You investigate and report. Read the code before you answer, cite the file and
line for every claim, and say plainly when you could not find something.

You never modify files and you never run commands.

Why this is the minimum

This reviewer can inspect the workspace, but it receives no editing or command tools. Start under ~/.clarvis/agents, where the role is available immediately and follows you across projects. A role committed to .clarvis/agents in a repository is withheld from every listing until you approve that workspace with /workspace-trust: the Markdown body becomes system prompt text, so the approval covers the exact bytes and has to be renewed each time the file changes.

Working patterns

Adapt it to work you actually do.

Open a pattern to see the complete files and the reason behind each choice.

Pattern 01 A Lead that splits a review across two specialists Configuration

You want one agent to own a review, hand the mechanical parts to cheaper agents, and merge what comes back into a single report. Three files, one of which is a Lead. The Lead uses a soft budget so a long review asks to continue rather than dying at the wall, and `default_spawn` decides who gets work when the model does not name anyone.

A Lead that splits a review across two specialists example

# ~/.clarvis/agents/review-lead.md
---
description: Review lead. Splits a review across specialists and merges their findings into one report.
model: anthropic/claude-sonnet-4-5
grants:
  - read_workspace
  - ask_user
can_spawn:
  - reviewer
  - test-writer
default_spawn: reviewer
iteration_limit: 40
budget:
  on_exceed: escalate
  total_token_limit: 3000000
  max_escalations: 3
---

You own the review. Split it into bounded pieces, hand each to a specialist with
the full context it needs, then check what comes back before you repeat it.

# ~/.clarvis/agents/reviewer.md
---
description: Read-only reviewer. Names concrete defects with file and line, and never edits.
model: anthropic/claude-sonnet-4-5
grants:
  - read_workspace
iteration_limit: 25
---

You read one bounded piece of a change and report defects you can point at.

# ~/.clarvis/agents/test-writer.md
---
description: Writes and runs tests for one bounded change. Edits test files only.
model: anthropic/claude-haiku-4-5
grants:
  - edit_workspace
  - run_commands
iteration_limit: 30
---

You write the test that proves a specific claim, run it, and report the command
you ran and its exact output.

Pattern 02 An image delegate, and the agent that routes to it Configuration

Your main agent runs on a model without vision, but people paste screenshots at it. Give one agent the `image` grant and a vision-capable model, then name it as the entry agent's `vision_delegate`. The grant does nothing on its own: the model must declare `vision` in the provider's `models` block in settings.json, and because the entry agent here is a Lead, the delegate must also appear in `can_spawn`.

An image delegate, and the agent that routes to it example

# ~/.clarvis/agents/looker.md
---
description: Describes screenshots, diagrams and UI mockups.
model: anthropic/claude-sonnet-4-5
grants:
  - read_workspace
  - image
iteration_limit: 10
---

You describe what is actually in an image. You do not guess at what is not
visible, and you say when something is unreadable.

# ~/.clarvis/agents/builder.md
---
description: General coding lead that hands images off for description.
model: anthropic/claude-haiku-4-5
grants:
  - read_workspace
  - edit_workspace
  - ask_user
can_spawn:
  - looker
vision_delegate: looker
iteration_limit: 40
---

You do the work. When a turn carries an image you cannot see, use what the
image delegate reports and say that is where the description came from.

Verify the behavior

Check the boundary, not just the happy path.

Use a small disposable task first. Confirm what works and what is deliberately unavailable before relying on the configuration in a real workflow.

01
The reviewer appears under the name taken from reviewer.md.
02
The review lead can delegate only to reviewer and test-writer.
03
The reviewer cannot edit or run commands; the test writer receives only the authority declared in its own profile.

Next guide

Give the team reusable know-how

Keep the roles focused and move repeatable methods into skills they can load only when needed.

Continue All guides