Anatomy of an Agent Definition

Chapter 1 established that every agent type has its own restricted set of tools, and explained why that restriction matters. This chapter covers exactly where that restriction — and everything else about how an agent behaves — actually gets defined: a small, structured file with a specific set of fields, each controlling one aspect of the agent's identity and behavior.

Where an Agent Is Defined

A custom agent is typically defined as a markdown file with a block of structured metadata — frontmatter — at the top, followed by ordinary written instructions in the body. The frontmatter is machine-readable configuration; the body is the agent's own system prompt, written in plain language exactly the way you'd brief a new colleague. Both parts matter, and they do genuinely different jobs.

The Frontmatter Fields

• name — a short, unique identifier for the agent.
• description — a summary of what the agent does and, critically, when it should be used. This field is what a routing decision (or a person choosing between several available agents) actually reads to decide whether this agent fits a given task — a vague description makes the agent hard to select correctly, even if the agent itself is well built.
• tools — an explicit allowlist of which tools this agent may use. Omitting a tool from this list means the agent cannot use it at all, regardless of what its instructions say — this is where Chapter 1's isolation principle is actually enforced.
• model (optional) — pins the agent to a specific model rather than inheriting whatever model the parent conversation is using, letting a simple, high-volume task use a smaller/faster model while a genuinely difficult one uses the most capable model available.

The System Prompt Body

Below the frontmatter, the body is the agent's actual briefing — written instructions describing its role, how it should approach a task, and any conventions it should follow. Because Chapter 1 established that an agent starts with no memory of anything outside what it's given, the system prompt has to stand on its own: it should read like documentation for someone who's never seen this project before, not like a note assuming shared context that only exists in your own head.

Tool Allowlists in Practice

The effect of the tools field is concrete, not theoretical. A dedicated read-only search agent might be granted every tool except the ones that edit or create files, making it structurally unable to change anything no matter what it's asked. A narrowly-scoped configuration agent, built for one specific settings task, might be granted only two tools — enough to read a file and edit it — and nothing else. Neither restriction is arbitrary: each one is sized to exactly what that agent's own job actually requires.

Model Selection: Matching Capability to the Task

Not every agent needs the most capable model available. A changelog-writer agent (as in the example above) is doing a small, well-defined formatting task — a faster, lighter model handles it perfectly well, at lower cost and higher speed. A code-review agent reasoning carefully about subtle correctness issues across an unfamiliar codebase genuinely benefits from the most capable model available. Choosing a model isn't just a cost setting — it's part of matching the agent's design to the actual difficulty of its job.

Hands-On Exercises