In the previous lesson, you learned how Claude automatically delegates tasks to three built-in subagents. The Explore subagent handles fast searches using Haiku with Read, Glob, and Grep tools. The general-purpose subagent tackles deeper analysis using Sonnet with full tool access. The Plan subagent manages research tasks by inheriting your conversation's model.

Real-world projects often require specialized workflows beyond what built-in subagents provide. Consider a Docusaurus project where you frequently need to review documentation for broken links, unclear explanations, or missing code examples. The general-purpose subagent could handle this if asked explicitly, but wouldn't check documentation proactively after changes.

Custom subagents solve this by allowing specialized workers tailored to your project. A documentation quality reviewer could monitor for doc changes and proactively offer reviews. A plugin architecture subagent could guide you through adding plugins following your project's specific conventions.

In this lesson, you'll learn two creation approaches: AI-assisted (describe in natural language, Claude generates configuration) and manual (full control over behavior). You'll understand how to write descriptions that trigger automatic invocation, select appropriate tools and models, and extend Claude's capabilities to match your project's unique requirements.

The fastest way to create a custom subagent is using Claude's AI-assisted flow. Type /agents in your conversation to open the subagent management interface showing existing subagents and a Create new agent option.

Let's create a documentation quality reviewer for Docusaurus. Type /agents, select Create new agent, and describe what your subagent should do:

The description includes: role (documentation quality expert), file types (MDX/Markdown), trigger phrase (Use PROACTIVELY after doc changes), and specific checks (broken links, code examples, SEO metadata).

Claude processes this and creates the subagent:

Claude wrote docs-quality-reviewer.md in .claude/agents/, chose Sonnet for reasoning capabilities, and selected tools appropriate for documentation review. The AI-assisted flow handled configuration details automatically based on your description.

Every custom subagent is defined by a Markdown file with YAML frontmatter in .claude/agents/. Ask Claude to show the definition:

The file has two parts: YAML frontmatter (structured metadata) and Markdown body (system prompt).

The frontmatter contains:

• name: Unique identifier matching the filename
• description: Controls automatic invocation by Claude
• tools: List of available tools (Read, Grep, Glob, Bash, WebSearch)
• model: sonnet for strong reasoning capabilities

The Markdown body is the system prompt guiding behavior. It establishes identity ("documentation quality specialist"), provides a step-by-step workflow, and defines output format with severity levels.

The description field determines when Claude invokes your subagent automatically by comparing your requests against all subagent descriptions.

Your docs-quality-reviewer description contains:

• Domain keywords: "Documentation," MDX, Markdown, "links," "code examples," "SEO metadata"
• Task terminology: "Reviews," "Checks"
• Trigger phrases: Use PROACTIVELY after doc changes

When you say "check the docs links," Claude matches "docs" and "links" against the description and invokes docs-quality-reviewer.

Compare two requests with different subagents:

Matches docs-quality-reviewer (contains "docs" and "links").

Matches plugin-architecture subagent (contains "plugin" and "adding").

Effective descriptions need:

• Specific domain keywords for clear matching
• File type mentions (e.g., MDX/Markdown) for context-aware triggering
• Trigger phrases (Use PROACTIVELY, ) for automatic invocation

The tools field lists which tools your subagent can access during execution:

• Read: Read file contents
• Write: Create or modify files
• Grep: Search text patterns
• Glob: Find files matching patterns
• Bash: Execute shell commands
• WebSearch: Query the internet

Match tools to your subagent's purpose. The docs-quality-reviewer needs Read (examine files), Glob (find docs), Grep (search patterns), WebSearch (validate links), and Bash (run validation scripts). A simple search subagent might only need Read, Grep, and Glob.

Consider security: Bash and Write allow modifications, so only enable them when necessary.

Manual creation provides complete control when AI-assisted generation doesn't meet specific requirements. Use /agents and select Create new agent, then follow the prompts to configure each element.

Creating a plugin-architecture subagent manually:

Step 1: Choose location

Select Project (.claude/agents/) for project-specific subagents that should be version-controlled with your code. Choose Personal (~/.claude/agents/) for subagents you want available across all projects.

Step 2: Enter description

Write a description that triggers automatic invocation using domain keywords ("plugin," "Docusaurus") and task terminology ("adding," "modifying").

Step 3: Write system prompt

You've learned to extend Claude's capabilities with custom subagents tailored to your project. The AI-assisted approach (/agents command) generates configurations from natural language descriptions. Every subagent is defined by a Markdown file in .claude/agents/ with YAML frontmatter (metadata) and a system prompt (behavior instructions).

Effective descriptions use domain keywords, task terminology, and trigger phrases for automatic invocation. Tool selection matches subagent capabilities—enable only necessary tools for efficiency. Model choice balances speed (Haiku) versus reasoning (Sonnet). Manual creation provides full control when precise customization is needed.

In upcoming practices, you'll create custom subagents hands-on using both AI-assisted and manual approaches. The CodeSignal environment comes pre-configured, so you can focus on designing effective subagents rather than setup.