A custom subagent is one Markdown file: YAML frontmatter for its settings, then a body that is its system prompt. Project-level subagents are typically stored at .claude/agents/<name>.md.1
Creating one with /agents
- Run
/agentsand choose Create new agent. - Choose a scope: project-level (this project only) or user-level (all projects on the machine).
- Configure it by hand, or describe the behaviour and let Claude generate the name, description, and system prompt. The course recommends generating as the easier start.
- Select tools, model, and UI colour.
- Save the generated file.
- Test on a representative task; if delegation does not trigger, refine the description.
As described in the course.1
Fields
| Field | Role |
|---|---|
name | Unique identifier; also usable as @agent <name> |
description | Tells Claude when to delegate and shapes the delegated prompt; one line, with escaped \n for breaks |
tools | The tools the subagent may use (see Least-privilege tool access) |
model | haiku (fast, light tasks), sonnet (middle ground), opus (complex analysis), or inherit (use the main conversation’s model) |
color | UI cue for which subagent is active |
| Body | The system prompt: focus, method, reporting |
As described in the course.1
A custom subagent can also take a skills field listing skills to load when it starts, for example skills: accessibility-audit, performance-check. The listed skills must already exist in an available skills directory; this suits isolated work that must apply a fixed, named set of standards.2
Example
---
name: code-quality-reviewer
description: Review specified code changes for quality and risk.
tools: Bash, Glob, Grep, Read
model: sonnet
color: purple
---
Review only the files named in the delegated task. Report findings by
severity and include enough evidence for the parent agent to verify them.What to write in description and the body is covered on Delegation contract.
Related
- Skill configuration: the matching format for skills.
- Source: Introduction to Claude Code Agent Skills
- Source: Introduction to Claude Code Subagents