Skip to content

BERD TASK · 0009 · BUILD YOUR CAST

Build an agent of your own

An agent is a markdown file: name, description, avatar, optionally a provider and model, and instructions. The file is easy. The role is the work. This page is how to get from "I keep explaining the same thing" to a saved agent that improves every time you correct it.

Steps at a glance

  1. Decide the role, not the capability
  2. Describe it to Agt. Builder — dictate if you can
  3. Review the draft in the builder rail
  4. Save, and know where it landed
  5. Use it on real work and correct it in place
  6. Keep instructions as workflow capture; put performance in model and effort

1. Decide the role, not the capability

Morgan, Berd's design lead, on Block's On The Block (September 2026), said her five agents could all run the same model; what makes them different is that each is told what to care about. A model "has all of the information in the world" and is average at everything until it is given a stake in something specific. So the question is not "what should this agent be able to do" but "what should it care about that a general model would be average at". A reviewer who checks every claim has a source. A chief of staff who knows what you always forget.

Write that sentence first. If you cannot, you want a skill, not an agent — see Write a skill and decide where it lives.

2. Describe it to Agt. Builder — dictate if you can

Start a chat with Agt. Builder, or with any agent and ask for the agent-builder skill. Say the need, the gap and the goal, in whatever order they come. Morgan's rule for this step: always dictate, never type — maximum intent and context, no time spent polishing a prompt up front. In the public build the way to do that is a Voice Conversation in a Goose chat with Agt. Builder; the composer's transcribe-and-submit dictation is compiled off the v0.6.4 public release and exists only in distributions that enable it. Agt. Builder's own instructions match: if purpose and tone come through, it drafts something concrete immediately; if the boundary or the voice is missing it asks one direct question, not a questionnaire.

It refuses two things worth knowing about: an agent with a blank or placeholder description, and a gender or gendered pronouns you did not ask for.

3. Review the draft in the builder rail

The draft appears in the agent builder rail beside the chat. Four fields are required before it can be saved — avatar, name, description, instructions — and the rail says which are missing. The avatar comes from the library: collections of gloopies, and since v0.6.3 any custom gloopie you have made appears first and can be reused on other agents. Provider and model can be set here; a provider that is not connected says so.

Read the instructions the way you would read a job description for someone joining your practice. If the draft has no boundary — what the agent should never do — ask for one.

[SCREENSHOT: T09-01 — builder rail with required fields]

[SCREENSHOT: T09-02 — avatar library]

4. Save, and know where it landed

Save. The rail's help line is exact: complete drafts are added to Agents when saved. Since v0.6.3 the new agent opens on its own profile. On disk it is ~/.agents/agents/<slug>.md, the slug being the name lowercased and hyphenated; a project-local agent goes to <project>/.agents/agents/ instead, and the builder defaults to global unless you asked otherwise. The gallery marks it File-backed: the file is the truth, and any editor can open it.

One thing the sources do not settle: what happens when provider and model are left blank. The law says an agent must have both before it can be invoked; whether Berd fills them from the session's choice or refuses to start is not verified. If a new agent will not start, set them explicitly.

[SCREENSHOT: T09-03 — saved agent profile]

[SCREENSHOT: T09-04 — the file on disk]

5. Use it on real work and correct it in place

The first draft is a hypothesis. Use the agent on a real task the same day, and when it misses, say so and ask it to update its own instructions — Morgan's phrase is exactly that, "update your instructions with that". Her engineering agent carries a line that makes this automatic: if corrected a couple of times, it asks whether to add the correction to its instructions. Put that line in yours. Agt. Builder treats a miss as a signal about the instructions, not the model having a bad day, and proposes the specific edit rather than a rewrite.

6. Keep instructions as workflow capture; put performance in model and effort

Brad, Block's AI lead, on the same programme: agent instructions do not drive performance "in the benchmarking sense". They are workflows — a direct capture of what you would otherwise type at the start of every conversation. Performance lives lower down: the model and the reasoning effort, which the composer toolbar exposes per chat and the agent file can pin. Tune those when the output is weak; tune the instructions when the output is the wrong shape.

Practitioner decision

Two documented ways to build: with Agt. Builder, in conversation — draft shown before anything is written, boundary and voice asked for, file saved at the right path with valid frontmatter; or by hand, in the agent editor form or directly in ~/.agents/agents/<slug>.md, following the agent-builder format. Recommendation: Agt. Builder for every first draft and any change of role or voice, because it enforces the description and boundary discipline a hand-written file skips; direct file edits for a one-line correction. The standard should also say whether engagement agents live project-local, so they leave with the engagement. Practitioner writes the standard here.

Last checked: Berd v0.6.4, 2026-09-11 — read from source and release notes, not yet tested in the app.

Learn more

Reference

Moment
apply
Takes
20 min
Steps
6
Verified
Berd v0.6.4 · 2026-09-11 · source-read
NEVER BESTUCK AGAINCLICK ME

Guide built with Berd, Claude and Codex · verified against Berd v0.6.4, 2026-09-11 · read from source, not yet tested in the app · Buzz Guide · About · not affiliated with Block