In Tutorial 01, you created a city, slung work to an
implicit agent, and added a rig. The implicit agents (claude, codex, etc.)
are convenient, but they have no custom prompt — they’re just the raw provider.
In this tutorial, you’ll define your own agents with specific roles and use them
to get work done.
We’ll pick up where Tutorial 01 left off. You should have my-city running with
my-project rigged.
Defining an agent
Each custom agent gets its own directory under agents/<name>/. Start by
creating a rig-scoped reviewer:
~/my-city
$ gc agent add --name reviewer
Scaffolded agent 'reviewer'
~/my-city
$ cat > agents/reviewer/agent.toml << 'EOF'
dir = "my-project"
provider = "codex"
EOF
agents/reviewer/ scaffold. The agent.toml file scopes the
reviewer to my-project and switches it from the city’s default claude
provider to codex.
This section sets provider = "codex". If you don’t have Codex installed and
configured, substitute another provider you do have (e.g., provider = "claude"); the rest of the walkthrough is the same.
gc prime returns when you don’t name an agent — without an agent argument,
it falls back to a generic worker prompt useful for a single-shot CLI
invocation:
~/my-city
$ gc prime
# Gas City Agent
You are an agent in a Gas City workspace. Check for available work
and execute it.
## Your tools
- `bd ready` — see available work items
- `bd show <id>` — see details of a work item
- `bd close <id>` — mark work as done
## How to work
1. Check for available work: `bd ready`
2. Pick a bead and execute the work described in its title
3. When done, close it: `bd close <id>`
4. Check for more work. Repeat until the queue is empty.
gc prime command tells you the prompt an agent is running with. In
tutorial 01 we learned that slinging work to
an agent created a bead; the agent’s prompt is what tells it how to pick up
and act on that work. Pass an agent name to inspect a specific agent:
gc prime mayor would print the mayor’s prompt;
gc prime my-project/reviewer would print the reviewer’s prompt once we’ve
written one.
To make the reviewer useful, we’ll write a prompt that tells it how to
discover work (the standard Gas City “find and execute” loop) and then
layer on the specifics of being a review agent. Create the reviewer prompt
to look like the following:
~/my-city
$ cat > agents/reviewer/prompt.template.md << 'EOF'
# Code Reviewer Agent
You are an agent in a Gas City workspace. Check for available work and execute it.
## Your tools
- `bd ready` — see available work items
- `bd show <id>` — see details of a work item
- `bd close <id>` — mark work as done
## How to work
1. Check for available work: `bd ready`
2. Pick a bead and execute the work described in its title
3. When done, close it: `bd close <id>`
4. Check for more work. Repeat until the queue is empty.
## Reviewing Code
Read the code and provide feedback on bugs, security issues, and style.
EOF
$ gc prime my-project/reviewer
# Code Reviewer Agent
You are an agent in a Gas City workspace. Check for available work and execute it.
... # contents elided as identical to the above
gc prime <agent-name> to get the contents of your custom
prompt for that agent. That’s a handy way to check on how the built-in agents or
your own custom agents are configured as you build out more of them over time.
If you wanted to get fancy, you could also set the model and permission mode:
dir = "my-project"
provider = "codex"
option_defaults = { model = "sonnet", permission_mode = "plan" }
agents/reviewer/agent.toml.
Now that your agent is available, it’s time to sling some work to it:
~/my-city
$ cd ~/my-project
~/my-project
$ gc sling my-project/reviewer "Review hello.py and write review.md with feedback"
Created mp-p956 — "Review hello.py and write review.md with feedback"
Auto-convoy mp-4wdl
Slung mp-p956 → my-project/reviewer
my-project rig, so from inside that
directory you can target it explicitly as my-project/reviewer. Gas City
started a Codex session, loaded the prompt from
agents/reviewer/prompt.template.md, and delivered the task to the rig-scoped
reviewer. You can watch progress with bd show as you already know. And when
the work is done, you can check the file system for the review you requested:
~/my-project
$ ls
hello.py review.md
~/my-project
$ cat review.md
# Review
No findings.
`hello.py` is a single `print("Hello, World!")` statement and does not present a meaningful bug, security, or style issue in its current form.
What’s next
You’ve defined agents with custom prompts, interacted with them through
sessions and configured different agents with different providers. From here:
- Sessions — session lifecycle, sleep/wake,
suspension, named sessions
- Formulas — multi-step workflow templates with
dependencies and variables
- Beads — the work tracking system underneath it all
