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.
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.
namename — identifier
How Claude Code and you refer to this agent. Use a short, clear slug. This is what you type when you invoke the agent explicitly.
name: migration-checker
descriptiondescription — when to use it
A sentence explaining what this agent does. Claude reads this to decide whether to invoke this agent automatically when planning a complex task.
description: Audits Prisma migrations for breaking changes that could affect the running application.
toolstools — allowed capabilities
A list of tools this agent is permitted to use. Restricting tools keeps the agent focused and safe. Common values: Read, Write, Bash, WebSearch.
tools: - Read # Write and Bash are intentionally excluded
bodyMarkdown body — instructions
The main instructions below the frontmatter. Write these like a detailed prompt: role, task, output format, and any constraints. The clearer, the better.
## Your role You are a read-only migration auditor... ## Output format Return a bullet list of risks...
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 Claude Code prompt box — no file editing needed.
/agentsList all available agentsShows every sub-agent Claude Code has discovered in .claude/agents/. Includes each agent's name and description so you can see what's available before invoking one.
/create-agentGenerate an agent file interactivelyStarts an interactive flow where Claude asks you what the agent should do, what tools it needs, and any constraints. It then writes the .md file in .claude/agents/ for you — no manual YAML editing required.
/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. Claude Code finds it in .claude/agents/ and runs it.
Automatic dispatch
When a task matches the agent's description, Claude Code will invoke it automatically — you don't need to name it explicitly.
description, the better Claude Code can decide when to invoke this agent automatically. Think of it as the agent's job posting.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 |
Creating a Sub-Agent — Quick Reference
File location
.claude/agents/<name>.md — auto-discovered on startup
name field
Short slug. Used to invoke the agent by name in prompts.
description field
One clear sentence. Drives automatic dispatch by Claude.
tools field
List only what's needed. Tool restrictions are enforced.
Markdown body
Role, task, output format, constraints. Clear = better results.
Test by name first
Always invoke explicitly once to verify it works as expected.
What's Next
You've created a custom sub-agent. Next: learn how MCP (Model Context Protocol) connects Claude Code to external data sources and tools.