The Agent Definition Format
Anatomy of an agent markdown file: frontmatter, system prompt, and tool configuration
Overview
You know why custom agents matter. Now you need to know how to build one. Every custom agent is defined by a single markdown file with YAML frontmatter placed in the .claude/agents/ directory of your repository. This file is the complete specification for the agent's identity, behavior, and capabilities. In this lesson, you will learn the anatomy of an agent definition file -- its structure, fields, and conventions -- so you can start creating agents with confidence.
The Agent File Location
Custom agents live in a specific location within the .claude/ directory at the root of your repository. The convention is straightforward:
Repository file structure showing agent definitions: the .claude/ directory contains an agents/ subdirectory with individual agent files (code-reviewer.md, test-writer.md, doc-generator.md, security-auditor.md), alongside settings.json. CLAUDE.md sits at the repository root.
Each .md file in .claude/agents/ defines one agent. The name frontmatter field identifies the agent. The filename is used to store and discover the definition, but it does not need to match the agent's name.
Check your agent definitions into version control. They are part of your project's infrastructure, just like CLAUDE.md.
Anatomy of an Agent Definition
An agent definition file has two main parts: YAML frontmatter that specifies the agent's metadata and configuration, and a markdown body that serves as the agent's system prompt. Let us look at a complete example and then break it apart.
This single file contains everything the agent needs. Let us examine each part.
The Frontmatter
The YAML frontmatter between the --- delimiters defines the agent's metadata and configuration. Two fields are required:
name is the unique identifier for the agent. Use lowercase letters and hyphens. This is what you use to invoke the agent (claude --agent code-reviewer) and what appears in the UI. It does not need to match the filename.
description tells Claude when to delegate tasks to this agent. Write a clear, specific description so Claude knows when this agent is the right choice. Include phrases like "Use after modifying code" or "Use proactively" to encourage automatic delegation.
Optional Frontmatter Fields
Beyond the two required fields, several optional fields control agent behavior:
| Field | Purpose | Example |
|---|---|---|
tools | Which tools the agent can use (allowlist) | Read, Glob, Grep |
disallowedTools | Tools to deny from inherited set | Write, Edit |
model | AI model to use | sonnet, haiku, opus, inherit |
permissionMode | How permission prompts are handled | default, plan, dontAsk |
maxTurns | Maximum agentic turns before stopping | 10 |
hooks | Lifecycle hooks scoped to this agent | See Module 7 |
memory | Persistent memory scope | user, project, local |
skills | Skills to preload into context | api-conventions |
mcpServers | MCP servers available to this agent | See Module 6 |
The most important optional field for controlling agent behavior is tools. When you specify tools, the agent can only use those tools -- nothing else. When you omit it, the agent inherits all tools from the main conversation. This is the primary mechanism for enforcing least-privilege access on a per-agent basis.
This agent can only read files and search. It cannot edit, write, or execute commands -- regardless of what its system prompt says or what a user asks it to do.
Agent Scopes
Agent definitions can live in different locations depending on how broadly they should be available:
| Location | Scope | When to use |
|---|---|---|
.claude/agents/ | Current project | Agents specific to this codebase, shared via version control |
~/.claude/agents/ | All your projects | Personal agents you use everywhere |
| Managed settings | Organization-wide | Agents deployed by IT/security teams |
--agents CLI flag | Current session only | Quick testing or automation scripts |
Plugin agents/ directory | Where plugin is enabled | Agents distributed with plugins |
When multiple agents share the same name, the one from the higher-priority location is used. Project agents take priority over user agents.
The System Prompt Body
Everything after the frontmatter is the system prompt -- the instructions that define how the agent behaves. This is where you encode the agent's personality, expertise, rules, and output format.
The system prompt is composed alongside your project's CLAUDE.md, not instead of it. Think of the relationship like this:
How an agent's effective prompt is composed: CLAUDE.md (project context, conventions, architecture) and the Agent Definition (role-specific instructions, behavior rules, output format) combine to produce the agent's effective prompt, which drives agent behavior.
Your CLAUDE.md tells the agent about the project. The agent definition tells the agent about its role. Together, they produce an agent that understands both what it is working on and what it is supposed to do.
Writing Effective Agent Prompts
The system prompt body follows the same principles you learned in Module 3 for writing CLAUDE.md instructions, but scoped to a specific role. Here are the key sections to include:
Role definition -- Tell the agent what it is and what it does. Be explicit about the persona:
Behavioral rules -- Define what the agent should and should not do. Use imperative language:
Output format -- If the agent produces structured output (like a review or a report), define the format explicitly:
Constraints -- Explicit boundaries prevent the agent from overstepping:
A Complete Minimal Agent
Here is the simplest useful agent -- a documentation helper with a focused role:
This agent is effective because it is focused. It knows exactly what it does (documentation), what files it touches (markdown only), and what style to follow (American English, existing structure). The tools frontmatter ensures it has only the capabilities it needs.
Common Agent Archetypes
While you can create agents for any purpose, most teams start with a few common archetypes:
| Archetype | Primary Action | Key Constraint | Typical Tools |
|---|---|---|---|
| Code Reviewer | Analyze and comment | Read-only, no modifications | Read, Glob, Grep |
| Test Writer | Create test files | No source code changes | Read, Write, Edit, Glob, Grep |
| Refactorer | Restructure code | No behavior changes | Read, Write, Edit, Bash, Glob, Grep |
| Doc Generator | Write documentation | Markdown files only | Read, Write, Edit, Glob, Grep |
| Security Auditor | Find vulnerabilities | Read-only, report format | Read, Glob, Grep |
| Migration Helper | Update APIs/patterns | Specific file scopes | Read, Write, Edit, Bash, Glob, Grep |
Each archetype translates into a focused agent definition file with role-appropriate frontmatter and instructions.
Naming Conventions and Organization
As your agent collection grows, good naming and organization become important:
- Use kebab-case for the
namefield:code-reviewer, notCodeReviewerorcode reviewer - Start names with the action or role:
review-security,write-tests,generate-docs - Keep agent definitions under 200 lines -- if the prompt is longer, you are probably trying to do too much in one agent
- The
descriptionfield should clearly state when to use the agent, not just what it does
A well-named agent with a clear description enables automatic delegation. When Claude sees a task that matches the description, it delegates without being asked.
Summary
Every custom agent is a markdown file in .claude/agents/ with YAML frontmatter and a system prompt body. The frontmatter requires two fields: name (the agent's identifier) and description (when to use it). Optional fields like tools, model, and permissionMode control capabilities. The system prompt body defines role, methodology, output format, and constraints. The agent definition works alongside CLAUDE.md -- project instructions provide shared context, while the agent definition provides role-specific behavior. In the next lesson, you will learn how to control what tools and permissions each agent has access to, turning the behavioral boundaries in your system prompt into enforced technical constraints.