Defining a Subagent

A role, tools and a prompt

In Claude Code a subagent is a Markdown file with frontmatter (name, description, optional list of allowed tools) and a system prompt as its body. Giving it only the tools it needs is the main safety control: a reviewer that can read files cannot accidentally edit them.

A read-only reviewer

Saved as .claude/agents/code-reviewer.md. The prompt fixes the output format so the main agent can use the result directly.

---
name: code-reviewer
description: Reviews changed code for bugs and security issues. Use after finishing a feature.
tools: Read, Grep, Glob
---

You are a careful code reviewer. Read the changed files and report:

- **Bugs**: file, line, why it is wrong
- **Risks**: security or data-loss concerns
- **Verdict**: approve or request changes

Do not edit files. Keep the report under 300 words.

Write the brief like a handoff

State the goal, the relevant paths, what was already tried and what to return. A vague brief like "look into the bug" produces a vague result.

Quick check: Why give a reviewer subagent only read tools?

• Read tools are faster to install
• It cannot accidentally modify files
• Write tools do not exist
• The model refuses otherwise