Custom Subagents — The Full AGENT.md Reference
AGENT.md files define named, reusable specialist subagents that Claude Code can invoke automatically or on demand. This article covers every frontmatter field, placement rules, and the design principles behind effective subagent definitions.
Quick Reference
- →Agent files live in .claude/agents/ (project) or ~/.claude/agents/ (personal)
- →The description field drives automatic selection — Claude uses it to pick the right agent
- →Use tools to restrict what an agent can do — principle of least privilege
- →Use model to assign Haiku for cheap tasks, Opus for complex reasoning
- →isolation: worktree gives the agent its own git branch and working directory
- →memory: project lets agents save learnings that persist across sessions
- →The body of AGENT.md becomes the agent's system prompt
- →permissionMode: auto is the least restrictive — use it only in controlled contexts
What Is an AGENT.md File?
An AGENT.md file is a markdown document with YAML frontmatter that defines a named, reusable subagent. Claude Code reads these files at startup and can invoke the defined agent automatically when a task matches its description, or explicitly when you @-mention it by name.
Every AGENT.md has two parts: frontmatter (the configuration) and body (the system prompt). The frontmatter specifies the agent's identity, capabilities, and constraints. The body is freeform markdown that becomes the agent's instructions — just like a CLAUDE.md, but scoped to this specific specialist.
When Claude Code encounters a task and has AGENT.md files available, it reads each agent's description and decides whether to delegate. Agents with precise, action-oriented descriptions get invoked reliably. Vague descriptions cause Claude to ignore the agent or use it incorrectly.