Claude Code Guide — Part 4: Agents

What an agent is

An agent is a markdown file at .claude/agents/<name>.md. The main session reads its description, decides the file matches what you're asking for, and spawns it as a separate session via the Agent tool. The agent runs in its own context, does the work, and returns a short report. The grep results, the partial reads, the scratch reasoning — all of that stays in the fork. Your main thread sees only the report.

The file has two parts. YAML frontmatter at the top (name, description, tools, model) and a system-prompt body underneath. The frontmatter tells the main session what the agent is for. The body tells the agent itself what to do, what its inputs and outputs look like, and what it shouldn't touch.

A naming note before the rest of the article uses it. Anthropic's docs call these subagents and the URL path is /sub-agents; the on-disk directory is .claude/agents/ and the slash command for managing them is /agents. This series sticks with agent in prose — it's what you'll type and what you'll see in the file system. The Agent tool (formerly the Task tool — Task(...) still works as an alias) is what the main session fires to delegate.

The full reference for the file format lives at docs.claude.com/en/docs/claude-code/sub-agents. Agents are loaded at session start; if you add a file by hand, restart Claude Code or run /agents to pick it up.

What goes in the frontmatter

The fields the prompts walk through, in plain language. Only name and description are required.

• name — short, kebab-case. The identifier the main session uses when it delegates. Lowercase letters and hyphens.
• description — what the agent does and when to reach for it. This is load-bearing. The main session reads this string and decides whether to fork, so vague descriptions silently fail to fire. Be concrete; name the trigger.
• tools — a comma-separated allowlist (e.g. Read, Grep, Glob, WebFetch). Omit the field and the agent inherits every tool the main session has. Effective access is this list intersected with the project's permission boundary — you can't widen permissions through an agent.
• model — sonnet, opus, haiku, a full model ID, or inherit. Defaults to inherit. Use haiku for routine work, sonnet for harder reasoning, inherit to match the main session.

The schema has more fields beyond these — disallowedTools, effort, color, and others — but the four above carry both agents you'll author here. The full list lives in the docs.

Author a read-only research agent

Start with the lowest-stakes shape: an agent that can grep, glob, read files, and fetch docs, but can't edit, write, or run shell commands. It's the agent you'll reach for most often once it exists — every time a task starts with "go figure out how the codebase does X" before any edits happen.

The first prompt in the side panel walks you through it. Claude asks one frontmatter question at a time — name, description, tools, model, body — then writes the file to .claude/agents/<name>.md. The directory gets created for you if it doesn't exist.

Pick something real. A repo researcher, a docs lookup agent, a question-answerer for a codebase you don't know well. Anything where reading is the whole job.

Open the prompts panel (right side on desktop, the floating button on mobile), copy Prompt 1, paste it into your Claude Code session.

Author an editing agent

The second prompt has the same shape, with editing tools in the allowlist. Same five-field interview, different content in the answers. The deliverable is a small artifact — a refactored function, a test file, a doc page from a spec — and the path to it involves intermediate work the main session doesn't need to see.

Tools widen carefully. Read and Edit at minimum. Write if the agent should create new files. Bash only if it needs to build or test. Less is more — the allowlist is the agent's contract with the main session about what it can touch.

Copy Prompt 2 from the side panel when you're ready.

Verify both fire

Authoring an agent doesn't guarantee the main session reaches for it. The failure mode is sharp: if the description is too vague, the main session does the work itself instead of delegating. The agent file is on disk, the description is in the routing pool, and nothing happens. No error, no warning — the main session just answers inline.

The third prompt is the check. For each agent, Claude drafts a real prompt that should obviously match the description, you paste it into a fresh main session, and you watch whether the Agent tool fires. If it doesn't, the description needs tightening — Claude helps you rewrite it and re-save. If you see Task(...) in your transcript instead of Agent(...), that's the historical alias; same delegation either way.

Copy Prompt 3 from the side panel when both agents are saved.

When to reach for an agent

A fork has a real cost. Fresh context, fresh model load, the main session waits for the report. For a one-line question you'd answer in five seconds yourself, the fork is overkill. Agents earn their place on tasks that match a few criteria.

Four questions decide it. Is the task long enough to leave a useful trail in the main thread? Would running it inline flood the main context with noise you won't reference again? Does it need least-privilege scoping the agent's tools whitelist can enforce? Will you want to validate the output as a separate role, with the doer and the validator in different contexts?

Prompt 4 walks the four questions one at a time and gives you a yes-fork / no-fork verdict at the end. It's the take-away tool — the one you run in a fresh main session before starting a new task, not the one that authors a file. Copy it from the side panel and paste it whenever you're not sure whether to delegate.

A short note on settings. The agent's effective tool access is the allowlist in the file intersected with the project's permission settings. You don't author the permission file by hand — Claude Code maintains it as you click through approvals.

What's next

Part 5 covers hooks — deterministic event handlers that fire on lifecycle events regardless of what the model decides. They're the one place in .claude/ where you do hand-author config. Continue at Part 5 — Hooks.