Overview

Custom agents in Claude Code are specialized AI assistants that can be invoked for specific tasks. They are defined as Markdown files with YAML frontmatter.

Agent File Structure

Storage Locations

  1. Project-level agents: .claude/agents/*.md (higher priority, team-shared)
  2. User-level agents: ~/.claude/agents/*.md (personal defaults)

Priority: Project agents override user agents with the same name.

Agent Specification Format

---
name: agent-identifier
description: When and why this agent should be used
tools: Tool1, Tool2, Tool3
model: sonnet
---


System prompt describing the agent's role, behavior, and instructions.

Configuration Fields

name (required)

  • Unique identifier for the agent
  • Must be lowercase with hyphens only
  • Example: code-reviewer, test-generator, bug-fixer

description (required)

  • Critical for proper agent delegation
  • Should be action-oriented and explain when to invoke the agent
  • Used by the main Claude instance to decide when to delegate tasks
  • Good: “Performs deep analysis of developer-AI collaboration patterns using temporal bridge memory”
  • Bad: “An agent that does analysis”

tools (optional)

  • Comma-separated list of tool names to restrict agent capabilities
  • If omitted, agent inherits all available tools from parent session
  • Security best practice: Limit tools to minimum required

Common tool categories:

  • File operations: Read, Edit, Write, Glob, Grep
  • Execution: Bash
  • Task management: TodoWrite
  • Web: WebSearch, WebFetch
  • MCP tools: Any MCP server tools like mcp__postgres__query

Example restrictions:

tools: Read, Edit, Write, Bash, Grep, Glob
tools: mcp__temporal-bridge__search_personal, mcp__temporal-bridge__search_all, TodoWrite, Read, Grep

model (optional)

  • Specifies which Claude model to use
  • Options: sonnet, opus, haiku, inherit
  • Default: sonnet
  • Use haiku for simple, fast tasks to reduce cost/latency

System Prompt Section

The content after the YAML frontmatter is the system prompt that defines:

  • Agent’s role and capabilities
  • Specific instructions and workflows
  • Examples of expected behavior
  • Output formats and requirements
  • Domain-specific knowledge

Best practices:

  • Be specific and detailed
  • Include examples where helpful
  • Define clear workflows/processes
  • Specify expected output formats
  • Document any special capabilities

Example Agent Structures

Minimal Agent

---
name: simple-reviewer
description: Reviews code for basic issues and style problems
tools: Read, Grep
model: haiku
---


You are a code reviewer focused on finding basic issues like:
- Unused variables
- Missing error handling
- Style inconsistencies


Be concise and provide line numbers for issues found.

Advanced Agent

---
name: collaboration-analyst
description: Performs deep analysis of developer-AI collaboration patterns using temporal bridge memory to identify improvements and track progress over time
tools: mcp__temporal-bridge__search_personal, mcp__temporal-bridge__search_all, TodoWrite, Read, Grep
model: sonnet
---


You are a specialized collaboration analyst that examines developer-AI interaction patterns...


## Capabilities
- Memory pattern analysis
- Collaboration effectiveness metrics
- Improvement recommendations


## Process
1. Search recent episodes
2. Analyze interaction patterns
3. Generate insights
4. Provide actionable recommendations


[Detailed instructions continue...]

Creating Agents

Via CLI

Terminal window
# Interactive agent creation
/agents
# Then select "Create New Agent"

Manually

Terminal window
# Create project-level agent
touch .claude/agents/my-agent.md


# Create user-level agent
touch ~/.claude/agents/my-agent.md

Invoking Agents

Agents are invoked automatically by the main Claude instance when the task matches the agent’s description. They can also be invoked explicitly using the Task tool:

Task(subagent_type: "agent-name", prompt: "Task description")

Agent Development Workflow

Important Limitation

Agents are loaded at Claude Code session start. Changes to agent files require a session restart to take effect.

Development Cycle

  1. Edit agent .md file
  2. Restart Claude Code session (required!)
  3. Test agent invocation
  4. Iterate

Testing Agents in Headless Mode

You can test agents without restarting the interactive session using headless mode:

Terminal window
# Test with simple prompt
claude -p "prompt text"


# Test with specific model
claude -p "prompt text" --model haiku


# Test with output format
claude -p "prompt text" --output-format json


# Continue previous conversation
claude -p "follow-up prompt" --continue

Headless mode flags:

  • -p, --print: Non-interactive mode (prints response and exits)
  • --output-format: Choose text, json, or stream-json
  • --model: Override default model
  • --system-prompt: Inject custom system prompt
  • --tools: Restrict available tools
  • --agents: Define custom agents inline (JSON)

Plugin-Based Agents

For shareable/distributable agents:

my-plugin/
├── .claude-plugin/plugin.json
└── agents/
    └── my-agent.md

Plugin agents can be:

  • Distributed across teams
  • Versioned independently
  • Integrated with Skills
  • Published to registries

Best Practices

1. Description Matters

The description is how the main Claude instance decides when to delegate:

  • Be specific about what tasks trigger this agent
  • Use action-oriented language
  • Mention key capabilities/domains

2. Tool Restriction

  • Security: Limit tools to minimum required
  • Focus: Fewer tools = more focused agent
  • Performance: Smaller tool set = faster execution

3. Detailed System Prompts

  • Include examples of expected behavior
  • Define clear process flows
  • Specify output formats
  • Document edge cases

4. Iterative Development

  • Start simple, add complexity as needed
  • Test with real-world scenarios
  • Refine based on actual usage
  • Document learnings

5. Model Selection

  • Use haiku for simple, fast tasks
  • Use sonnet (default) for balanced performance
  • Use opus for complex reasoning tasks
  • Consider cost vs. capability tradeoffs

Common Patterns

Analysis Agent

tools: Read, Grep, TodoWrite
model: sonnet

Focused on code analysis, searching, and reporting.

Code Generation Agent

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

Can read context, generate/modify code, and run tests.

Research Agent

tools: WebSearch, WebFetch, Read, Write
model: sonnet

Gathers information from web sources and documents findings.

Specialized Domain Agent

tools: MCP tools, Read, TodoWrite
model: opus

Deep domain expertise requiring complex reasoning.

Troubleshooting

Agent Not Being Invoked

  • Check description is clear and specific
  • Ensure agent name is unique
  • Verify agent file is in correct location
  • Restart Claude Code session

Agent Lacks Necessary Tools

  • Add required tools to tools: list
  • Or remove tools: field to inherit all tools

Agent Gives Poor Results

  • Enhance system prompt with more detail
  • Add examples of expected behavior
  • Consider using a more capable model
  • Add relevant domain knowledge to prompt

References

  • Claude Code Documentation: Built-in /help command
  • Existing Agents: Check ~/.claude/agents/ for examples
  • Plugin System: For distributable agent packages