Creating Custom Claude Code Subagents

This skill guides you through designing and creating custom subagent configurations for Claude Code CLI.

Official Documentation

For the most current information, reference:

• •https://code.claude.com/docs/en/sub-agents

When to Create a Custom Agent

Use Built-in Agents When:

• •Explore: Fast, read-only codebase exploration (uses Haiku)
• •Plan: Research and planning tasks
• •General-purpose: Complex multi-step tasks with full capabilities
• •Bash: Terminal commands in separate context

Create Custom Agents When:

• •You need a specialized domain expert (code reviewer, data scientist, security auditor)
• •You require specific tool restrictions for safety or focus
• •You want custom hooks for validation or lifecycle events
• •You need a focused system prompt for consistent behavior
• •You want to share configurations with your team via version control

Agent Design Process

1. Gather Requirements

Ask the user to clarify:

• •What specific task should this agent handle?
• •What tools does it need? What tools should it NOT have?
• •Should this be user-level (all projects) or project-level?
• •Does it need hooks for validation or setup/cleanup?

2. Choose Location

3. Write the Description (Critical!)

The description determines when Claude delegates to your agent. Write it like you're telling Claude: "Use this agent when..."

Good descriptions:

• •"Expert code review specialist. Proactively reviews code for quality, security, and maintainability"
• •"Execute read-only database queries with SQL validation"
• •"Debugging specialist for errors, test failures, and unexpected behavior"

Bad descriptions:

• •"Code helper" (too vague)
• •"Does stuff with files" (no trigger keywords)
• •"My agent" (meaningless)

4. Configure Tool Access

Three approaches:

• •Inherit all (default): Omit tools field entirely
• •Allowlist: Use tools to specify only permitted tools
• •Denylist: Use disallowedTools to remove specific tools

Common tool sets:

• •Read-only: Read, Grep, Glob, Bash
• •With editing: Read, Edit, Write, Bash, Grep, Glob
• •Minimal: Read, Grep, Glob (no Bash)

5. Set Permission Mode

6. Add Hooks (Optional)

Hooks enable validation or lifecycle events. See ./references/hooks-and-validation-patterns.md for examples.

Quick Configuration Reference

---
name: my-agent                    # Required: lowercase, hyphens only
description: When to use this     # Required: determines delegation
model: sonnet                     # Optional: sonnet|opus|haiku|inherit
tools: Read, Grep, Glob           # Optional: allowlist (inherits all if omitted)
disallowedTools: Write, Edit      # Optional: denylist
permissionMode: default           # Optional: permission handling
skills: my-skill, other-skill     # Optional: preload skill context
hooks:                            # Optional: lifecycle hooks
  PreToolUse: [...]
  PostToolUse: [...]
---

Your system prompt goes here. This is the context and instructions
the agent receives when invoked.

For detailed field documentation, see ./references/agent-configuration-options.md.

Common Patterns

Read-Only Reviewer

---
name: code-reviewer
description: Expert code review specialist for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. Analyze code and provide specific, actionable feedback.

Database Reader with Validation

---
name: db-reader
description: Execute read-only database queries with SQL validation
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You execute SQL queries. Only SELECT statements are permitted.

Focused Domain Specialist

---
name: security-auditor
description: Security specialist for vulnerability assessment and secure coding review
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
---

You are a security expert. Focus on OWASP Top 10, authentication, authorization,
input validation, and secure data handling.

For more examples, see ./references/agent-examples.md.

Validation Checklist

Before finalizing your agent:

• • Name: Lowercase letters and hyphens only, unique identifier
• • Description: Clear, specific, includes trigger keywords
• • Tools: Minimally scoped for the task (principle of least privilege)
• • System prompt: Focused instructions for the agent's role
• • Location: Appropriate scope (project vs user)
• • Hooks: If used, validation script tested and working

Creating the Agent File

1. •

   Create the file at the appropriate location:

   bash

   # Project-level (version-controlled)
   mkdir -p .claude/agents
   
   # User-level (personal)
   mkdir -p ~/.claude/agents
   

2. •

   Write the agent file with .md extension:

   bash

   # Example: .claude/agents/code-reviewer.md
   

3. •

   Test by asking Claude to use the agent or let it auto-delegate based on description

Using Agents

Once created, agents are available automatically:

• •Claude delegates based on matching descriptions
• •Explicitly invoke: "Use the code-reviewer agent to analyze this file"
• •Manage via /agents command in Claude Code

Reference Files

• •./references/agent-configuration-options.md — All frontmatter fields explained
• •./references/hooks-and-validation-patterns.md — Hook examples and validation scripts
• •./references/agent-examples.md — Curated agent configurations for common use cases