Skip to content
Promptsio
Search prompts, tools, agents…

How-to guide

How to create a subagent in Claude Code

A step-by-step walkthrough for making a specialised agent: the file, its header, its tools and how to use it. Includes a complete working example.

  • Time 12 min
  • Level Beginner
  • Steps 6
  • Updated

A subagent is a specialised assistant that Claude Code can hand work to. Each one has its own instructions and its own tool permissions, and works in a separate context so your main conversation stays tidy.

Step by step

0/6 done

  1. 1 Understand where it lives

    A subagent is one markdown file. Put it in .claude/agents/ in your project to use it there, or in ~/.claude/agents/ to use it in every project.

  2. 2 Create the file

    Name it after the job, for example .claude/agents/code-reviewer.md. You can also run /agents in Claude Code to create one through a guided screen.

  3. 3 Write the header 

    ---
name: code-reviewer
description: "Reviews recent code changes for bugs, security and readability. Use proactively after code is changed."
tools: Read, Grep, Glob, Bash
---

    The description tells Claude when to hand work to this agent. tools lists what it may use; leave it out to allow all tools.

  4. 4 Write the system prompt

    Below the header, describe the role, the method and the output.

    You are a senior engineer who reviews code changes.

When invoked:
1. Run git diff to see what changed.
2. Read the changed files.
3. Check correctness, security, tests and readability.

Report Must fix, Should fix and Nice to have. Do not edit files.

  5. 5 Use it

    Ask directly: "Use the code-reviewer agent on my last commit." A well-written description also lets Claude choose the agent on its own.

  6. 6 Start from a ready-made one

    Browse the agents library, download a file, and edit it to fit your project.

Was this helpful?