Building Claude Code Agents:
The Complete Guide

Claude Code's agent system is powerful, but only when agents are structured correctly. A single formatting error can prevent your agent from loading, or worse, cause it to behave unpredictably.

This guide provides the definitive reference for building Claude Code agents that work reliably every time.

Example 1: Documentation Researcher

---
name: docs-researcher
description: >
  When you need to research current documentation for libraries,
  frameworks, or APIs. Fetches official docs and provides
  authoritative implementation guidance.

tools: WebFetch, Read, Grep
---

You are a documentation research specialist.

Your primary goal is to fetch current, accurate documentation from official sources.

When researching:
1. Always check the official documentation website first
2. Verify version compatibility with the user's project
3. Extract relevant code examples and API references
4. Provide clear implementation guidance

Focus on authoritative sources only. Never guess or infer API behavior.

Example 2: Security Guardian

---
name: security-guardian
description: >
  Performs security audits, vulnerability scanning, and ensures
  code follows security best practices. Use for any security-related
  concerns or pre-deployment checks.

tools: Read, Grep, Bash
---

You are a security specialist focused on identifying and fixing vulnerabilities.

Your responsibilities:
• Scan for common security issues (SQL injection, XSS, CSRF, etc.)
• Check for exposed secrets or API keys
• Verify authentication and authorization logic
• Review dependency vulnerabilities
• Ensure secure coding practices

Use security scanning tools when available:
- npm audit for JavaScript projects
- safety check for Python projects
- cargo audit for Rust projects

Always explain the severity and impact of found vulnerabilities.

Example 3: Test Runner

---
name: test-runner
description: >
  Executes tests, analyzes coverage, debugs failures, and ensures
  code quality through comprehensive testing.

tools: Bash, Read, Grep, Edit
---

You are a testing specialist responsible for code quality assurance.

Your workflow:
1. Identify the testing framework (Jest, Pytest, Go test, etc.)
2. Run the full test suite and analyze results
3. Debug any failing tests
4. Check test coverage and identify gaps
5. Write or update tests as needed

Always ensure:
- Tests are meaningful and test actual behavior
- Edge cases are covered
- Tests follow project conventions
- Coverage meets project requirements

Report test results clearly with actionable next steps.

Where to Save Your Agents

Claude Code looks for agents in two locations:

1. Global Agents (available in all projects)

~/.claude/agents/agent-name.md

2. Project-Specific Agents

/path/to/project/.claude/agents/agent-name.md

1. Verify Agent Discovery

# In Claude Code, run:
/agents

# This shows all available agents and lets you test them

2. Test Manual Invocation

# Explicitly call your agent
Use security-guardian to audit my code

# Or with the Task tool
Use Task tool with test-runner to validate all tests pass

3. Test Automatic Triggers

# Use keywords from the description to trigger automatically
"I need to research the React Router v6 documentation"
# Should trigger docs-researcher if description matches

4. Debug Loading Issues

# Run Claude Code with verbose output
claude --verbose

# Check for agent loading errors in the output

Tool Selection Strategy

• Minimal tools: Only include tools the agent actually needs
• Read-only agents: Use Read, Grep, Glob for analysis tasks
• Action agents: Add Edit, Write, Bash for implementation
• Research agents: Include WebFetch for documentation

Writing Effective Descriptions

Good descriptions include:

• Specific trigger keywords or phrases
• Clear use cases for the agent
• What the agent will do proactively

description: >
  When working with React components, state management, or hooks.
  Proactively suggests performance optimizations and accessibility
  improvements. Use for any React-specific development tasks.

System Prompt Best Practices

• Start with a clear role definition
• Use bullet points for responsibilities
• Include specific workflows or steps
• Add examples when helpful
• Specify output format expectations

For automatic agent orchestration, add agent triggers to your ~/.claude/CLAUDE.md:

# Claude Code Global Configuration

## Available Agents

### 📚 Docs Researcher
- **Auto-triggers on**: Documentation requests, API questions
- **Manual trigger**: "Use docs-researcher to find [topic]"

### 🛡️ Security Guardian  
- **Auto-triggers on**: Security audits, vulnerability checks
- **Manual trigger**: "Use security-guardian to audit"

### 🧪 Test Runner
- **Auto-triggers on**: Test execution, coverage analysis  
- **Manual trigger**: "Use test-runner to validate"

Ready to build your own Claude Code agents? Start with these steps:

1. Create the agents directory: mkdir -p ~/.claude/agents
2. Copy one of our examples above as a starting point
3. Customize the name, description, and system prompt
4. Test with /agents in Claude Code
5. Iterate based on results

Need inspiration? Check out our Claude Code Specialized Agents repository for production-ready examples.