Anatomy of an agent file

You'll finish with: You can write agent frontmatter without looking it up.

An agent is a text file. Top half tells Claude when to use it, bottom half tells the agent how to behave.

Every field that matters

nameThe handle. Lowercase, hyphens. Required.
descriptionHow Claude decides to hand work over. The most important line in the file.
toolsWhat it's allowed to touch. Leave it out and it inherits everything.
modelhaiku for cheap and fast, sonnet for most, opus for hard thinking. Also takes fable, a full model ID, or inherit. Leave it out and you get inherit — whatever model your main conversation is on, not a fixed default.
memoryGives it notes that survive between sessions. Most people miss this.
— then the prompt —Plain instructions. Numbered steps beat paragraphs.

The description does the work

Claude reads every agent's description to decide who gets the job. Write it the way you'd describe the role to a new hire, and say when to use it.

Do this now
  1. Make a folder in your business folder: .claude/agents/
  2. Save the file below inside it as researcher.md
  3. Restart Claude and ask it: "research [any company] for me"
smith-plumbing/
├── CLAUDE.md
└── .claude/
    └── agents/researcher.md
---
name: researcher
description: Researches a prospect, competitor or market and
  returns a short brief. Use before a sales call or before
  writing outreach. Read-only.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
memory: project
---

You research things and come back with a brief, not a transcript.

1. Work out what decision this research is feeding.
2. Prefer the company's own site over listicles.
3. Cross-check anything that matters. One source is a claim.

Return, in this order:
- The short version — three lines
- What they do, plainly
- Signals they have the problem we solve
- The angle — how we'd open a conversation
- What you couldn't confirm

Never invent a detail to fill a gap. An unknown is a finding.

That tools line isn't the whole story. Setting memory: project makes Claude Code add Read, Write and Edit on top of whatever you listed, so the agent can keep its own notes. On a researcher that's deliberate — remembering what it found last time is the point of the field. It does mean this one isn't strictly read-only, and on an agent like a reviewer that matters. Chapter 5 covers it.

How to know it worked

Ask it to research a company. You should see it hand off to the researcher, then come back with a short brief — not a wall of search results.

If nothing happens, the folder is wrong. It must be .claude/agents/ inside the folder you opened Claude in.

All courses · Start here · Privacy