Building Agents

Module 4: Building Agents

The jump from skill to agent is smaller than you’d expect. Same file format, same YAML header, same markdown body. The difference is a tools line and, usually, a model line.

What those two lines unlock is substantial.

The Structure

An agent definition lives in ~/.claude/agents/ as a single markdown file. Here’s draft-reviewer stripped to its essentials:

---
name: draft-reviewer
domain: writing
description: Review AND FIX any draft for AI slop, writing craft, and voice consistency. Uses local LLM pre-scan for cost optimisation. Invoke with "review this draft", "check my writing", or "audit content".
tools: Read, Write, Edit, Skill, Glob, mcp__local-llm__local_classify
model: sonnet
---

The tools declaration is the contract. It tells Claude Code exactly what this agent is permitted to do. Read, Write, Edit — file operations. Glob — directory traversal. Skill — the ability to invoke other skills. mcp__local-llm__local_classify — a specific tool from a local MCP server that routes classification work to Ollama rather than the main model.

That last one is worth noting. The tool declaration lets you mix Claude’s native tools with MCP server tools in a single agent. The agent is the composition point.

Tool Permissions as Design

Every tool you include is a capability. But it’s also a trust boundary.

draft-reviewer has Skill in its tools. That’s what lets it invoke writing-quality and voice-editor as sub-processes. Without Skill, it would have to replicate those skills’ instructions inline — defeating the composability that makes the system valuable.

Bash is notably absent from draft-reviewer. There’s no reason a writing reviewer needs shell access. Keeping tools minimal means fewer surface areas for unexpected behaviour and cleaner error reasoning when something goes wrong.

The discipline: include only the tools the agent actually needs. Not the tools it might need. Not the tools the skill you’re copying had. The tools this specific agent requires to do its job.

The model Declaration

Most agents run on sonnet. It’s fast, capable, and economical for most tasks.

Some use opus. The sbc-writer agent, which writes the Second Brain Chronicles newsletter, runs on Opus. That’s a deliberate choice — the output carries the author’s name publicly, and the additional quality ceiling is worth the cost for that specific task.

The model field gives you per-agent model routing. Different tasks have different requirements. A classification agent doesn’t need the same capability as a public-facing writer. Route accordingly.

The Role Section

After the YAML, the agent body typically opens with a <role> block:

<role>
You are a writing quality reviewer AND EDITOR that systematically assesses drafts using two specialised skills plus unique checks, then APPLIES ALL FIXES directly to the file.

Your job is NOT to produce reports for someone else to implement. Your job is to:
1. Run the quality checks
2. Identify issues
3. Fix them using Edit tool
4. Report what you changed
</role>

The role block establishes the agent’s identity and its core constraints before any workflow begins. It’s the first thing in context after the header — the agent reads it before anything else.

Keep roles specific and constraint-forward. The most important thing to establish is what the agent is NOT doing, because that’s where agents drift.

Workflow Sections

The rest of the agent body is typically workflow: phases, steps, decision rules, output formats. draft-reviewer has a five-phase workflow — pre-scan, skill-based analysis, unique checks, apply fixes, report.

Structure the workflow so each phase has:

• A clear trigger (what causes this phase to run)
• A defined output (what it produces or changes)
• A defined next step (what comes after)

Agents that lack this structure tend to meander. The phases give Claude a progress model — it knows where it is in the task and what’s left to do.

Delegation

One pattern worth understanding: agents can call other agents.

sbc-writer tells its user to route the draft through draft-reviewer before finalising. draft-reviewer itself invokes writing-quality and voice-editor as sub-skills via the Skill tool. Each agent handles its domain; the output of one becomes the input of the next.

This is delegation. The orchestrating agent doesn’t need to know how its sub-agents work — it trusts them to do their job and move the output forward. The skill/agent boundary enforces clean interfaces: each piece knows its inputs, produces its outputs, and doesn’t care what runs before or after.

Testing Your Agent

Before you ship an agent into regular use, test it against failure cases, not just happy paths. For a writing reviewer: give it a draft that’s genuinely clean. Does it find nothing and say so, or does it fabricate issues to justify its existence? For an agent that writes to files: give it an edge case where the output location doesn’t exist. Does it fail gracefully?

The most valuable test is the one that catches what the agent does when it’s wrong, not when it’s right.

---

Next: agents that orchestrate other agents across a full pipeline.