Agent Builder

Overview

Create high-quality Claude Code sub-agents that follow official Anthropic patterns. Every agent is a markdown file with YAML frontmatter (metadata) and a body (system prompt), stored in ~/.claude/agents/ for global use or .claude/agents/ for project-local scope.

When to Use

• Creating a new sub-agent from scratch
• Improving or restructuring an existing agent
• Choosing the right frontmatter configuration (model, tools, color)
• Writing effective agent system prompts
• Deciding between global vs. project-local agent placement

Agent Creation Process

Step 1: Understand the Agent's Purpose

Before writing anything, clarify:

1. What specific task does this agent handle? (e.g., "reviews PRs for security issues")
2. When should Claude invoke it? (trigger conditions)
3. What tools does it need? (Read, Write, Edit, Bash, Glob, Grep)
4. What model should it use? (inherit, opus, sonnet, haiku)
5. Should it be global or project-local?

Step 2: Write the Frontmatter

The YAML frontmatter controls agent metadata and invocation behavior.

Required fields:

Optional fields:

Step 3: Write the Description (Critical)

The description determines whether Claude finds and invokes the agent. Follow these rules:

1. Start with "Use this agent when..." to define trigger conditions
2. Include <example> blocks showing concrete user interactions
3. Cover synonyms — if the agent does "code review", also mention "review code", "check code quality"
4. Mention proactive triggers if the agent should auto-invoke (e.g., "Use PROACTIVELY after writing code")

Official Anthropic example pattern:

description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:

<example>
Context: User has created a PR and wants quality review
user: "Can you review PR #123 for code quality?"
assistant: "I'll use the pr-quality-reviewer agent to analyze the PR."
<commentary>
PR review request triggers the pr-quality-reviewer agent.
</commentary>
</example>

Simpler community pattern (also valid):

description: Design RESTful APIs, microservice boundaries, and database schemas. Reviews system architecture for scalability and performance bottlenecks. Use PROACTIVELY when creating new backend services or APIs.

Step 4: Write the System Prompt (Body)

The body below the frontmatter is the agent's system prompt. Structure it with these sections:

1. Role Statement — One sentence defining who the agent is.

You are an expert code quality reviewer specializing in security, performance, and maintainability.

2. Core Responsibilities — Numbered list of primary duties.

**Core Responsibilities:**
1. Analyze code changes for quality issues
2. Check adherence to project coding standards
3. Identify security vulnerabilities
4. Suggest performance improvements

3. Process/Workflow — Step-by-step instructions for how the agent operates.

**Process:**
- Start by reading the relevant files to understand context
- Identify patterns and anti-patterns in the code
- Check for OWASP top 10 vulnerabilities
- Verify error handling completeness
- Assess test coverage adequacy

4. Output Format — Define what the agent returns.

**Output Format:**
Provide findings as a structured report:
- **Critical**: Issues that must be fixed before merge
- **Warning**: Issues that should be addressed
- **Suggestion**: Optional improvements
- Include file paths and line numbers for each finding

Step 5: Validate and Install

1. Save the file to the appropriate location:

   • Global: ~/.claude/agents/<agent-name>.md
   • Project: .claude/agents/<agent-name>.md

2. Validate the file structure:

   • YAML frontmatter is properly delimited with ---
   • name field matches the filename (without .md)
   • description is present and descriptive
   • Body contains actionable instructions
   • Tools listed in tools array are valid Claude Code tools

3. Restart Claude Code to load the new agent.

Model Selection Guide

Tool Selection Guide

Only restrict tools when the agent should NOT have access to certain capabilities. Omitting the tools field gives the agent access to all tools.

Common Agent Categories

Quick Reference

Additional Resources

• references/agent-prompt-patterns.md — Detailed system prompt patterns and anti-patterns
• examples/complete-agent-example.md — Full working agent with all sections
• examples/minimal-agent-example.md — Bare-minimum agent template