Creating Your First Subagent Definition

Making a subagent is refreshingly simple. It is a single Markdown file. The frontmatter sets a few fields, and the body is the system prompt that tells the agent how to behave.

Where the file goes

Put it in one of two places:

• .claude/agents/<name>.md for a project agent, shared with your team through git.
• ~/.claude/agents/<name>.md for a personal agent you can use in any project.

The frontmatter fields

Four fields are supported: name (lowercase with hyphens), description (when Claude should delegate to it), tools (an allowlist, covered later in this series), and model (a model alias). The body below the frontmatter is the agent's system prompt.

Here is a small, complete example:

---
name: test-writer
description: Writes unit tests for a given file or function. Use when asked to add test coverage.
model: sonnet
---

You write focused unit tests. Read the target file first, match the
project's existing test style, and cover the important edge cases.
Return only the test file and a one-line summary of what you covered.

Try it out

Save the file, then manage and inspect your agents with the /agents command. You can invoke it by asking Claude to "use the test-writer subagent to add tests for this file."

Keep the system prompt concrete. Tell the agent what to read first, what conventions to follow, and what to return. A tight prompt gives you a predictable helper instead of a vague one.