# Authoring an agent

An agent in Smithy is just a small bundle of decisions: a name, a one-line
description, the system prompt that gives it its voice, the slice of tools it is
trusted with, and the model that backs it. Get those five things right and the
rest takes care of itself. This guide is the order I work in.

## Start from a profile, not a blank page

Most agents you want to build are a variation on one of three shapes: a coder
that edits files and runs commands, a researcher that only reads and
summarises, or a reviewer that inspects a change and reports. Pick the nearest
profile and override only what differs. A profile already pins a sane tool
collection, a model, and a starter prompt, so naming the agent is enough to get
something that runs:

    defineAgent({ name: "release-notes" }, "researcher")

Then narrow it. Override the description and system prompt to describe *this*
agent's job, not the generic kind. Leave the tool collection and model alone
unless you have a concrete reason to change them.

## Name it like a file

The name is a kebab-case identifier — lowercase letters, digits, and hyphens.
Treat it like a filename, because that is roughly what it is: a stable handle you
will type, log, and look up. `code-reviewer`, not `Code Reviewer`. Keep it short
and specific. If two agents would want the same name, one of them is mis-scoped.

## Write the description for a human scanning a list

The description is one line and it is for people, not the model. Imagine a menu
of twenty agents — the description is what tells a reader which one to pick. Say
what the agent *does* and what it *touches*. "Summarises a PR diff and flags
risky changes" beats "a helpful review assistant."

## Let the precedence rules do the merging

You never assemble the full blueprint by hand. `defineAgent` merges three
layers, highest priority first: your spec, then the named profile, then a
built-in baseline that fills any remaining gap. The only field with a surprise
is `tags` — your tags *replace* the profile's rather than merging, so you stay
in full control of how the agent is catalogued. Everything is validated once at
the end, so a half-finished spec fails loudly instead of producing a broken
agent.

## Verify before you trust it

A blueprint that validates is well-formed, not necessarily *correct*. Before you
wire an agent into anything real, read its system prompt back as if you were the
model receiving it, confirm the tool collection matches the access you intend,
and sanity-check the model id. The cheapest bug to fix is the one you catch by
re-reading your own spec.
