Meta Agent Creator

Custom Agent Creator

Overview

Subagents are specialized AI assistants defined as Markdown files with YAML frontmatter. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When a task matches a subagent's description, the parent conversation delegates to it automatically, preserving main context while enforcing constraints.

When to use: Isolating high-volume operations (tests, logs), enforcing read-only access for reviewers, routing simple tasks to cheaper models, running parallel research, creating reusable team workflows.

When NOT to use: Tasks requiring frequent back-and-forth, quick targeted changes, workflows needing nested delegation (subagents cannot spawn subagents), latency-sensitive operations where fresh context gathering is costly.

Quick Reference

Common Mistakes

Delegation

• Agent pattern discovery: Use Explore agent to find existing agents in .claude/agents/
• Interactive creation: Use /agents command for guided setup with Claude generation
• Code review of agent files: Use Task agent to validate system prompts and configuration

References

• Agent configuration: YAML fields, file locations, and priority order
• Tool selection: access patterns, common combinations, and model guide
• Templates: ready-to-use agent patterns for common workflows

Agent Configuration

File Structure

Subagent files use YAML frontmatter for configuration followed by the system prompt in Markdown:

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

The frontmatter defines metadata and configuration. The body becomes the system prompt. Subagents receive only this system prompt plus basic environment details, not the full parent system prompt.

File Locations and Priority

When multiple subagents share the same name, the higher-priority location wins.

Project subagents in .claude/agents/ should be checked into version control for team sharing.

YAML Frontmatter Fields

Required Fields

Optional Fields

Permission Modes

The permissionMode field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.

---
name: auto-fixer
description: Automatically fix lint errors. Use proactively after lint failures.
tools: Read, Edit, Grep, Glob
permissionMode: acceptEdits
---

If the parent uses bypassPermissions, it takes precedence and cannot be overridden by the subagent.

Skill Preloading

Use the skills field to inject skill content into a subagent's context at startup. Subagents do not inherit skills from the parent conversation.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---
Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

The full content of each skill is injected into the subagent's context, not just made available for invocation.

Lifecycle Hooks

Define hooks directly in the subagent's frontmatter. These hooks only run while that specific subagent is active.

---
name: safe-editor
description: Edit files with automatic linting after changes
tools: Read, Edit, Grep, Glob
hooks:
  PostToolUse:
    - matcher: 'Edit|Write'
      hooks:
        - type: command
          command: './scripts/run-linter.sh'
---

Project-Level Hooks

Configure hooks in settings.json that respond to subagent lifecycle events in the main session:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [{ "type": "command", "command": "./scripts/cleanup.sh" }]
      }
    ]
  }
}

SubagentStart supports matchers to target specific agent types. SubagentStop fires for all subagent completions regardless of matcher values.

CLI-Defined Agents

Pass subagent definitions as JSON via the --agents flag for session-only agents:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

The JSON format uses prompt for the system prompt (equivalent to the markdown body in file-based agents). CLI-defined agents have the highest priority and are not saved to disk.

Built-in Agents

Claude Code includes several built-in subagents that are used automatically:

Explore Thoroughness Levels

When invoking Explore, specify a thoroughness level: quick for targeted lookups, medium for balanced exploration, or very thorough for deep analysis.

Foreground vs Background Execution

• Foreground: Blocks main conversation until complete. Permission prompts pass through to the user.
• Background: Runs concurrently. Permissions are pre-approved before launch; unapproved prompts are auto-denied. MCP tools are not available in background subagents.

Press Ctrl+B to background a running task, or ask to "run this in the background."

Resuming Agents

Each subagent invocation creates a new instance with fresh context. To continue a previous subagent's work, ask to resume it. Resumed subagents retain their full conversation history.

Transcripts are stored at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl.

Disabling Agents

Prevent specific subagents from being used via permission rules:

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(my-custom-agent)"]
  }
}

Or via CLI:

claude --disallowedTools "Task(Explore)"

Agent Templates

Code Reviewer

A read-only subagent that reviews code without modifying it. Uses restricted tools (no Edit or Write) and a structured output format.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger

A subagent that can analyze and fix issues. Includes Edit for modifying code with a clear workflow from diagnosis to verification.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:

1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:

- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:

- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Research Agent

A read-only agent with web access for gathering external information and documentation.

---
name: researcher
description: Research specialist for documentation lookup, API exploration, and gathering external information. Use when needing external context or documentation.
tools: Read, Grep, Glob, WebFetch, WebSearch
model: haiku
---

You are a research specialist. Gather information from codebases and external sources to answer questions thoroughly.

When invoked:

1. Understand the research question
2. Search the codebase for relevant context
3. Fetch external documentation if needed
4. Synthesize findings into a clear summary

Present findings as:

- Key facts and answers
- Relevant code locations
- External documentation links
- Recommendations based on findings

Be thorough but concise. Focus on actionable information.

Test Runner

A subagent focused on running and analyzing test results. Isolates verbose test output from the main conversation.

---
name: test-runner
description: Run tests and analyze failures. Use proactively after code changes to verify correctness.
tools: Read, Grep, Glob, Bash
model: haiku
---

You are a test execution specialist. Run tests, analyze failures, and report results concisely.

When invoked:

1. Identify which tests to run based on the request
2. Execute the test suite
3. Analyze any failures
4. Report results in structured format

Output format:

## Test Results

**Status**: PASS / FAIL
**Total**: X tests, Y passed, Z failed

## Failures (if any)

1. **test-name**: Brief description of failure
   - Expected: ...
   - Actual: ...
   - File: path/to/test:line

## Recommendations

- Suggested fixes for failures

Security Auditor

A focused auditor with sonnet for deeper reasoning about security patterns.

---
name: security-auditor
description: Audit code for security vulnerabilities and best practices. Use proactively before releases or when reviewing authentication, authorization, or data handling code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a security auditor. Analyze code for vulnerabilities and security best practices.

When invoked:

1. Identify the scope of the audit
2. Search for common vulnerability patterns
3. Check authentication and authorization logic
4. Review data handling and input validation
5. Assess dependency security

Check for:

- SQL injection, XSS, CSRF
- Hardcoded secrets or API keys
- Missing input validation
- Insecure authentication patterns
- Improper error handling that leaks information
- Unsafe dependency versions
- Missing rate limiting
- Insecure data storage

Report format:

## Security Audit

### Critical (must fix before release)

1. [Finding]: [Location] - [Description and fix]

### High (fix soon)

1. [Finding]: [Location] - [Description and fix]

### Medium (address in next sprint)

1. [Finding]: [Location] - [Description and fix]

### Recommendations

- General security improvements

Exploration Agent

A lightweight read-only agent for discovering and documenting patterns in the codebase.

---
name: <domain>-explorer
description: Explore and understand <domain> patterns in the codebase. Use when researching existing implementations or understanding architecture.
tools: Read, Grep, Glob
model: haiku
---

# <Domain> Exploration Specialist

You explore and document <domain> patterns in this codebase.

## Exploration Process

1. **Scope** - Identify relevant directories and file patterns
2. **Discover** - Find implementations using Grep and Glob
3. **Analyze** - Read and understand patterns
4. **Document** - Summarize findings

## Key Patterns to Look For

- <Pattern 1>
- <Pattern 2>
- <Pattern 3>

## Output Format

\`\`\`markdown

## <Domain> Exploration Results

### Files Found

| File | Purpose |
| ---- | ------- |
| ...  | ...     |

### Patterns Identified

#### <Pattern Name>

[Description and examples]

### Recommendations

[How to apply these patterns]
\`\`\`

Data Scientist

A domain-specific subagent for data analysis with explicit model selection for capable analysis.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:

1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:

- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:

- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Database Query Validator

Demonstrates using PreToolUse hooks for conditional tool validation. Allows Bash but blocks write SQL operations.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: 'Bash'
      hooks:
        - type: command
          command: './scripts/validate-readonly-query.sh'
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:

1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

The validation script for the hook:

#!/bin/bash
# ./scripts/validate-readonly-query.sh
# Blocks SQL write operations, allows SELECT queries

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

Best Practices for Agent Design

1. Start with `/agents` command to generate an initial agent with Claude, then customize 2. One clear purpose per agent with a focused system prompt 3. Include trigger phrases in description ("Use proactively when...", "Use immediately after...") 4. Limit tool access to only what the agent needs 5. Include structured output formats for consistent results 6. Route simple tasks to haiku and complex analysis to sonnet or opus 7. Check project agents into version control for team sharing 8. Test and iterate on system prompts for better results

Role Description Best Practices

Be Specific

# Good - specific to project

You are a senior code reviewer for a TanStack Start + Better Auth project.

# Bad - too generic

You are a helpful assistant.

Include Context

# Good - includes key conventions

Review code for:

- File naming: kebab-case
- Imports: Use @/ alias
- Types: Use `type` not `interface`

# Bad - no context

Review the code.

Reference Skills

## Skill References

| Area     | Skill           |
| -------- | --------------- |
| Forms    | `tanstack-form` |
| Auth     | `auth`          |
| Database | `database`      |

Use Proactive Triggers

Include trigger phrases in descriptions:

• "Use proactively after..."
• "MUST BE USED when..."
• "Use when encountering..."

These help Claude know when to automatically invoke the agent.

Output Format Examples

Structured Review

## Summary

Brief overall assessment in 1-2 sentences.

## Issues Found

1. **[Category]**: [File:line] - [Description]
   - Fix: [Suggested fix]

## Recommendations

- [Optional improvements not blocking approval]

## Verdict

APPROVE / REQUEST CHANGES / NEEDS DISCUSSION

Investigation Report

## Analysis

**Error**: Exact error message
**Location**: src/module/file.ts:123
**Type**: Runtime / Type / Build

## Root Cause

Explanation of why this happened.

## Evidence

- src/file1.ts:45 - Finding description
- src/file2.ts:78 - Related finding

## Fix

Specific code changes needed.

## Verification

Steps to confirm the fix works.

Exploration Summary

## Exploration Results

### Files Found

| File                   | Purpose            |
| ---------------------- | ------------------ |
| src/auth/index.ts      | Auth configuration |
| src/auth/middleware.ts | Route protection   |

### Patterns Identified

#### Pattern Name

Description with code examples.

### Recommendations

How to apply these patterns in new code.

Tool Selection

Available Tools

Subagents can use any of Claude Code's internal tools. By default, subagents inherit all tools from the main conversation, including MCP tools.

Tool Access Control

Allowlist with tools

Restrict a subagent to specific tools only:

---
name: read-only-reviewer
description: Reviews code without modifications. Use proactively after code changes.
tools: Read, Grep, Glob
---

When tools is specified, the subagent can only use those tools. Omit the field entirely to inherit all tools from the parent conversation (including MCP tools).

Denylist with disallowedTools

Remove specific tools from the inherited set:

---
name: safe-researcher
description: Research agent that cannot modify files
disallowedTools: Write, Edit
---

This inherits all tools except Write and Edit. Use disallowedTools when you want most tools but need to block a few.

Combining Both

You can use both fields together. The disallowedTools removes tools from the tools allowlist:

---
name: restricted-bash
description: Run diagnostics without file modifications
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
---

Common Tool Combinations

Read-Only Reviewer

tools: Read, Grep, Glob

For code review, style checking, and analysis tasks. Cannot modify files or run commands.

Investigator with Diagnostics

tools: Read, Grep, Glob, Bash

For debugging, test execution, and system diagnostics. Can run commands but cannot modify source files directly.

Agent That Can Fix Issues

tools: Read, Grep, Glob, Edit

For automated fixes like lint corrections or refactoring. Can modify existing files but cannot create new ones or run commands.

Full Modification Agent

tools: Read, Grep, Glob, Edit, Write, Bash

For implementation tasks that require creating files, editing code, and running builds/tests.

Research Agent

tools: Read, Grep, Glob, WebFetch, WebSearch

For documentation lookup, API research, and gathering external information.

All Tools (Default)

# Omit the tools field entirely

Inherits everything from the parent conversation, including MCP tools. Use when the agent needs full capabilities.

Conditional Tool Validation with Hooks

For finer control than allowlist/denylist, use PreToolUse hooks to validate specific operations:

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

The hook script receives JSON via stdin with the tool input in tool_input. Exit code 0 allows the operation, exit code 2 blocks it and feeds the stderr message back to the agent.

Model Selection Guide

Decision Tree

Is this a simple checklist or search task?
  Yes -> haiku
  No -> Does it require modifying code or deep reasoning?
    Yes -> sonnet
    No -> Does it involve architecture or cross-system decisions?
      Yes -> opus
      No -> sonnet (safe default)

Model Configuration

---
name: fast-reviewer
model: haiku
---

• Model alias: sonnet, opus, or haiku
• `inherit`: Uses the same model as the main conversation
• Omitted: Defaults to inherit

Cost Optimization Patterns

Route simple tasks to haiku to reduce costs:

---
name: style-checker
description: Check code style and formatting. Use proactively after file edits.
tools: Read, Grep, Glob
model: haiku
---

Reserve sonnet or opus for tasks requiring deeper analysis:

---
name: security-auditor
description: Audit code for security vulnerabilities. Use proactively before releases.
tools: Read, Grep, Glob, Bash
model: sonnet
---