Create your first subagent

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

1. 01

   Step 1 of 4: Add the subagent file

   Save one Markdown file in the folder Claude Code scans for project subagents.

   The practice kit already has this file. In your own project, save it at the same path. You can also ask Claude to write a subagent for you; /agents now only points you to these folders.

   .claude/agents/diff-reviewer.md · MarkdownCopy

   ---
   name: diff-reviewer
   description: Reviews uncommitted changes for bugs, missing tests and work outside the task. Use after code changes, before the work counts as done. Never edits files.
   tools: Read, Grep, Glob, Bash, PowerShell
   model: inherit
   ---
   
   You review the uncommitted changes in this repository with fresh eyes. You
   did not write them and you have not seen the conversation that produced them.
   
   1. Run `git diff` and `git diff --staged` to see what changed. If both are
      empty, say so and stop.
   2. Read each changed file and the tests that cover it.
   3. If CLAUDE.md or package.json names a test command, run it once.
   
   Report only problems that affect correctness or the task you were given:
   
   - Bugs: wrong results, inputs that are not handled, broken edge cases.
   - Behaviour the change adds or alters without a test.
   - Changes outside what the task needed.
   
   For each finding, give the file and line, what is wrong and a suggested fix.
   Leave style preferences out.
   
   You have no Edit or Write tool. Do not change files with shell commands
   either: you report, and the main conversation decides what to fix.
   
   If nothing matters, reply "No blocking issues" and list what you checked.
   

   your-project/

   • folder .claude
     • folder agents
       • diff-reviewer.mdNewshared with anyone who clones the repo
   • folder src

   Check it worked

   The file starts with --- on its first line. If the agents folder is new, restart Claude Code: a running session only watches folders that existed when it started.

   It worked — next step Not yet
2. 02

   Step 2 of 4: Check what it can do

   Read the frontmatter: the description decides when Claude uses it, the tools decide what it can touch.

   .claude/agents/diff-reviewer.md

   name: diff-reviewer

   How you and Claude refer to it

   description: Reviews uncommitted changes…

   What Claude reads to decide when to delegate

   tools: Read, Grep, Glob, Bash, PowerShell

   An allowlist with no Edit or Write. Both shells, so it can run git diff on any system

   model: inherit

   Same model as your session

   Note: A shell can still change files, so the prompt tells it not to. Shell commands still go through your permission rules.

   Check it worked

   In Claude Code, type @: diff-reviewer is listed as an agent in the typeahead.

   If it didn’t work

   It is not in the list

   A file with no name is read as documentation. For a missing description or broken YAML, claude --debug shows why it was skipped.

   It worked — next step Not yet Back
3. 03

   Step 3 of 4: Give it something to review

   Have Claude make one small change and leave it uncommitted.

   In Claude Code

   You type: › Add a --rush option to the quote command that adds 25% to the subtotal before the discount. Don’t commit.

   – What happens: In your own project, ask for any small change you would want reviewed.

   Check it worked

   git status lists at least one modified file.

   It worked — next step Not yet Back
4. 04

   Step 4 of 4: Hand the review to it

   Ask for the subagent by name, or @-mention it to make sure it runs.

   In Claude Code

   You type: › Use the diff-reviewer subagent to review my uncommitted changes

   – What happens: A diff-reviewer(…) row appears while it works, then Claude passes on its report.

   Check it worked

   A report with file and line for each finding, or "No blocking issues" and what it checked. Ask Claude to fix what matters; the reviewer itself edits nothing.

   It worked — finish Not yet Back