Anthropic’s Claude Code documentation explains how developers can define reusable custom subagents in Markdown files, scope them to a repository or a local user environment, and assign focused roles such as planning, review and documentation.
Anthropic has published documentation detailing custom subagents for Claude Code, giving developers a file-based way to define specialized assistants for recurring work.
According to Anthropic’s Claude Code subagents documentation, a custom subagent is defined in a Markdown file with YAML frontmatter. The definition can include a name, description, task instructions and tool permissions, allowing a developer to create a more narrowly directed assistant than the primary coding conversation.
Anthropic describes subagents as a way to delegate focused tasks while keeping the main Claude Code session centered on the broader objective. Rather than repeatedly supplying the same long prompt, developers can place role-specific guidance in a reusable definition file.
That approach can apply to tasks such as reviewing code for security issues, preparing implementation plans, investigating test failures, refactoring code or producing documentation in a required style. The documentation does not present these roles as fixed presets; instead, developers write the instructions and configure the tools available to each subagent.
Anthropic documents two locations for storing these definitions. Subagents placed in a repository’s .claude/agents/ directory are available for that project. This model can be useful when an assistant needs to follow repository-specific conventions, understand an application’s architecture or support a team’s established development practices.
Because project-level files can be committed alongside source code, they can also be reviewed, updated and shared through a team’s normal version-control process. In practice, that makes the files a potential place to capture repeatable AI-assisted workflows without embedding the same instructions in every developer prompt.
For reusable personal configurations, Anthropic says developers can store subagent files in ~/.claude/agents/. Definitions in that local directory are available across the user’s projects, making it possible to retain broadly useful roles—such as a general code reviewer or writing helper—without copying files into every repository.
Anthropic’s blog post on using subagents in Claude Code similarly frames the feature around work that benefits from its own dedicated context. The company distinguishes this specialized context from the main conversation, where a developer may be managing a larger implementation task.
Community projects are also publishing example configurations for the feature. The open-source iannuttall/claude-agents repository provides agent definition files and instructs users to install them in either .claude/agents/ for a project or ~/.claude/agents/ for broader local use.
Its examples cover roles including refactoring, content writing, frontend design, product-requirements drafting, task planning and security auditing. These are community-made configurations, not official Anthropic presets, but they illustrate the range of roles that can be expressed through the documented file format.
The practical value of a custom subagent will depend on how clearly its role is bounded, how well its instructions reflect the project’s needs and which tools it is permitted to use. Anthropic’s documentation positions the capability as a configurable mechanism for organizing repeated development work rather than a replacement for developer judgment.
Reusable specialists for coding tasks Anthropic has published documentation detailing custom subagents for Claude Code, giving developers a file based way to define specialized assistants for recurring work.
According to Anthropic’s Claude Code subagents documentation, a custom subagent is defined in a Markdown file with YAML frontmatter.
The definition can include a name, description, task instructions and tool permissions, allowing a developer to create a more narrowly directed assistant than the primary coding conversation.
Continue reading
