Audience: Those new to Claude Code and those designing custom subagents for the first time

Purpose: Understand “when to create one,” “what to write,” “how to use it safely,” and “how to validate it” through practical templates and concrete examples

Contents

1. Subagent Basics
2. Determining Whether a Custom Subagent Is Necessary
3. Recommended Initial Setup
4. Agent Definition and Delegation Brief
5. Final Recommended Core Contract
6. Meaning of Frontmatter
7. Leaf Specialist and Orchestrator
8. Example of a Completed Role Profile
9. Delegation Brief
10. Validation and Completion Criteria
11. Division of Responsibilities among CLAUDE.md, Rules, Skills, and Hooks
12. Execution Modes
13. Setup Procedure
14. Quality Evaluation and Lifecycle
15. Glossary
16. Final Checklist

1. Subagent Basics

1.1 What Is a Subagent?

A subagent is a worker to which the main Claude Code delegates specific specialized work.

The parent agent is responsible for the following:

• Understanding user requirements
• Task decomposition
• Selecting the delegate
• Determining whether to execute in parallel
• Integrating multiple results
• Final acceptance
• Providing the final response to the user

The specialized subagent is responsible for the following:

• The single delegated responsibility
• Research or modifications within the specified scope
• Gathering evidence
• Applicable verification

The most important principle is as follows.

Combining research, design, implementation, review, and fixes within a single agent makes the authority, completion criteria, and location of responsibility ambiguous.

1.2 Advantages of subagents

1. Large volumes of search results and logs can be isolated from the main conversation
2. Implementation, review, and debugging can be separated
3. Available tools can be restricted according to role
4. The same specialized work can be repeated using the same quality standards
5. Only the necessary conclusions can be returned to the main conversation

2. Determine whether a custom subagent is necessary

Before creating a custom definition, check whether a simpler mechanism is sufficient.

Guidelines for creating one

Consider creating one when two or more of the following apply.

• Repeatedly delegating work of the same kind
• You want to isolate large volumes of logs and search results from the main context
• Dedicated tool restrictions are required
• A dedicated model, effort setting, and turn limit are required
• A dedicated validation contract is required
• Domain-specific decision criteria are required
• We want to standardize the return format to the parent

Examples of things that are better not to create

This is because they overlap with built-in functionality or have an overly broad scope of responsibility.

3. Recommended initial configuration

The following four roles are sufficient to start with.

• Explore: Codebase exploration
scoped-implementer: Implementation of approved changes
• spec-code-reviewer: Independent review of completed diffs

After gaps have actually been identified, add roles such as test-engineer and security-reviewer.

4. Agent Definition and Delegation Brief

Agent Definition

Place information that remains almost unchanged each time.

• Name
• Automatic selection criteria
• Single responsibility
• Standing In Scope / Out of Scope
• Available tools
• Role-specific decision criteria
• Completion criteria
• Return format to the parent

Delegation Brief

Place information that changes from task to task.

• Objective of this task
• Target files or diffs
• Out of scope
• Specifications, logs, and errors
• Constraints
• Deliverables
• Acceptance criteria
• Required validation

If task-specific information is embedded in the Agent Definition, outdated conditions may remain in other tasks, so keep them separate.

5. Final Recommended Core Contract

Copy the following as a common skeleton, and replace the angle brackets and Role Profile.

6. Meaning of Frontmatter

name

Use a unique lowercase kebab-case name that makes the responsibility clear.

Good examples:

Bad examples:

description

This is not a self-introduction, but a routing rule for automatic delegation.

Good example:

tools

The explicit list serves as the allowlist of available tools.

Leaf Specialist does not include Agent.

model

For general-purpose definitions, inherit is recommended.

effort

maxTurns

This is a resource limit, not a quality setting.

Conditional fields

• skills: Preload procedures needed every time
• memory: Only when long-term knowledge reuse is required
• isolation: worktree: Parallel implementation or independent diffs
• omitClaudeMd: Self-contained tasks that do not require project instructions
• permissionMode: Set it only when there is a clear reason
• hooks: When agent-specific automated processing is required
• mcpServers: When agent-specific external integration is required

7. Leaf Specialist and Orchestrator

Leaf Specialist

Complete only your own specialized work and return it to the parent.

Representative examples:

• scoped-implementer
• spec-code-reviewer
• root-cause-debugger

Do not include Agent in tools.

Orchestrator

Use only when coordinating multiple subtasks that can be independently verified.

Allowlist subagents.

Example to avoid:

The Orchestrator is responsible for validating subagent results, resolving conflicts, and integrating them.

8. Example of a completed Role Profile

Scoped Implementer

Frontmatter:

Specification Code Reviewer

Root-Cause Debugger

9. Delegation Brief

Task-specific information passed by the parent at startup.

Ensure that even a non-fork subagent can start with this Brief alone.

10. Verification and Completion Criteria

Verification is not a list of commands, but a mechanism for proving the acceptance criteria.

Priority:

1. Direct verification of the acceptance criteria
2. Reproduction of the original bug
3. focused test
4. regression test
5. typecheck, lint, build
6. Verification in the running application
7. Broad suite or CI

Bad example:

Good example:

11.CLAUDE.md, Rules, Skills, and Hooks

Prompts, CLAUDE.md, Rules, Skills, and agent body text are nondeterministic instructions interpreted by the model.

Hard requirements are enforced through deny rules, Hooks, sandbox, CI, etc.

Recommended directory:

12. Execution Modes

Foreground

• Implementation
• Interactive debugging
• Operations requiring approval
• Tasks where the parent agent checks progress along the way

Background

• Large-scale log analysis
• Read-only investigation
• Independent review from multiple perspectives

Worktree

• Parallel implementation
• Independent changes
• Prototyping isolated from the main working tree

As a rule, consider foreground execution or a worktree for implementation work that requires editing.

13. Introduction Procedure

1. Choose one responsibility to delegate repeatedly
2. Check whether it can be replaced by a built-in agent or Skill
3. Determine the closest competing role
4. Write the description in the form “Capability. Use when Trigger. Do not use for Conflict.”
5. Choose the minimum necessary tools
6. Copy the Core Contract
7. Write In Scope and Out of Scope
8. Add one Role Profile
9. Pass task-specific information through the Delegation Brief
10. Test with 2 positive examples, 2 negative examples, and 1 boundary case
11. Run validation corresponding to the acceptance criteria
12. Audit with /doctor prompt-audit .claude/agents
13. Test with 5 to 10 actual tasks
14. Decide whether to retain, revise, integrate, or delete

14. Quality Evaluation and Lifecycle

Score each item from 0 to 2 points.

Guidelines:

• 16 to 18 points: Ready for practical use
• 13 to 15 points: Improve after a small-scale trial
• 12 points or below: Redesign

Maintain

• Used repeatedly
• Better suited than built-in features or Skills
• Fewer misdelegations

Consolidate

• Positive and negative examples for multiple agents are nearly identical
• Have the same tools and Role Profile
• Cannot explain how to distinguish between them

Delete

• Not used for a long period
• Replaced by built-in functionality
• A Skill was sufficient
• No improvement in misdelegation

15.

16. Final Checklist

• The built-in Explore or Skill is insufficient
• The primary responsibility can be stated in one sentence
• The closest competing role can be identified
• The description includes Capability, Trigger, and Conflict
• The tools are kept to the minimum necessary
• Leaf does not include Agent in tools
• Orchestrator allowlists child agents
• There are In Scope and Out of Scope sections
• Task-specific information has been separated into the Delegation Brief
• It can be started with just the Brief even without forking
• Acceptance criteria are observable
• Verification aligns with the acceptance criteria
• Use passed only when execution succeeds
• The parent can integrate it without re-investigating
• Absolute conditions do not rely on wording alone
• The conditions for removing this definition are defined

If you cannot explain even one item, first try using a regular prompt, a built-in agent, or a Skill.

Official References

• Best practices for Claude Code
• Create custom subagents
• Extend Claude with skills
• How Claude remembers your project