Creating Custom Agents

A custom agent is an agent configuration stored in a Markdown file. It gives the assistant a reusable role, such as code reviewer or planner, with instructions and optional model settings.

Use a repository agent

If your repository defines an agent, select it from the agent list or pass its file on the command line:

boldcreate --agent-file .boldcreate/agents/reviewer.agent.md

The path is relative to the workspace folder. Repository agents may also appear in the agent picker when you start a task.

Create an agent file

An agent file is Markdown. The body contains instructions. Optional YAML frontmatter can set its name, description, and model:

---
name: Reviewer
description: Reviews changes for correctness and style
model: claude-sonnet-4-6
---

Review code changes. Point out bugs first, then style issues. Never edit files yourself.

Tool access and approvals

A custom agent has full tool access, like the built-in Agent, unless its instructions and configuration specify otherwise. Your approval mode still applies. Use Ask or Plan when you need read-only behavior rather than a custom agent with tools. See Models and agents and Approvals and safety.

Add temporary instructions

For instructions that should apply to one run only, use --append-system-prompt instead of creating an agent file:

boldcreate --append-system-prompt "Answer in British English. Prefer pnpm over npm."

For standing project instructions, use Project context and instruction files.