Create a Sub-Agent
The previous lesson explained what sub-agents are and why they matter. Now you'll build one. A sub-agent is defined by a single Markdown file — it describes the agent's role, the tools it can use, and any rules it should follow. Claude Code reads that file and can invoke the agent by name.
What you'll build
A Migration Checker sub-agent. It reads your Prisma schema and recent migration files, then reports any field renames, deletions, or type changes that could break the running app. It never edits files — it only reads and reports.
| Property | Value |
|---|---|
| Role | Read-only auditor |
| Tools | Read files only |
| Output | Risk summary |
Where sub-agent files live
Sub-agent definitions are Markdown files stored in a specific folder. Claude Code scans this folder on startup and makes every agent it finds available by name.
.claude/agents/ folder is the standard location. Files placed here are automatically discovered — no registration or config file needed.The four parts of an agent file
Every sub-agent file is a Markdown file with a YAML frontmatter block at the top. The frontmatter declares the agent's identity and capabilities. The Markdown body contains its instructions.
| Field | Purpose | Example |
|---|---|---|
| name | Identifier used to invoke the agent | migration-checker |
| description | When Claude should use this agent automatically | Audits Prisma migrations for breaking changes |
| tools | Allowed capabilities — enforced by Claude Code | Read only (Write and Bash excluded) |
| body | Role, task, output format, and constraints | ## Your role You are a read-only migration auditor... |
The complete agent file
Here is the finished migration-checker.md agent. Create this file at .claude/agents/migration-checker.md in your project.
tools: [Read] restriction means this agent physically cannot write files or run shell commands — even if the instructions asked it to. Tool restrictions are enforced by Claude Code, not just by the instructions.Built-in slash commands
Claude Code has two slash commands for working with agents. Type them directly in the prompt box — no file editing needed.
/agents — list all available agents
Shows every sub-agent Claude Code has discovered in .claude/agents/, including each agent's name and description.
/create-agent — generate an agent file interactively
Starts an interactive flow where Claude asks what the agent should do, what tools it needs, and any constraints. It then writes the .md file in .claude/agents/ for you.
/create-agent is the fastest way to get started. You can always open the generated file and refine the instructions manually afterwards.Using the agent
Once the file exists in .claude/agents/, you can invoke the agent in two ways.
Invoke by name
Use the agent's name field directly in your prompt.
Automatic dispatch
When a task matches the agent's description, Claude Code invokes it automatically — you do not need to name it explicitly.
description, the better Claude Code can decide when to invoke this agent automatically.Common agent patterns
Most custom sub-agents fit one of these four patterns. Pick the one that matches your use case and adjust the name, description, and instructions.
| Pattern | Tools | Good for |
|---|---|---|
| Read-only auditor | Read only | Schema checks, security reviews, license scans |
| Code generator | Read + Write | Scaffold components, generate types, write boilerplate |
| Command runner | Read + Bash | Run test suite, lint, build, report results |
| Researcher | Read + WebSearch | Look up docs, find package versions, check changelogs |
Before you continue
- Sub-agents live in
.claude/agents/<name>.mdand are auto-discovered. - YAML frontmatter sets name, description, and tools; the body holds instructions.
- Tool restrictions are enforced — not just suggested in the instructions.
- Use
/create-agentfor a fast start, or write the file by hand. - Next lesson: MCP in Claude Code.
What's Next
You've created a custom sub-agent. Next: MCP (Model Context Protocol) — connecting Claude Code to external data sources and tools.