Claude Code Agents Reference

Complete reference for creating and managing specialized agents in Claude Code.

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

Agent Format

---
allowed-tools: |
  Tool1, Tool2, Tool3
description: "When this agent should be invoked"
model: inherit  # Optional: inherit (default), sonnet, opus, or haiku
---

# Agent Name

## Role
Single, focused purpose (one responsibility only)

## When to Use
Specific triggering scenarios

## Responsibilities
- Focused task 1
- Focused task 2

## Knowledge Base
Domain-specific patterns and practices

Key Features

• Single Responsibility: ONE clear purpose per agent
• Context Isolation: Separate windows prevent pollution
• Clear Triggers: Description defines activation conditions
• Model Selection: Choose optimal model for task (inherit, sonnet, opus, haiku)
• Version Control: Commit project agents to .claude/agents/

Agent Locations

Agents can be stored in two locations:

Best Practice:

• Project agents - Domain experts (database, UI, testing) that team shares
• User agents - Personal productivity tools, custom workflows, learning aids

Guidelines for Creating Agents

Single Responsibility

• ONE clear purpose (non-negotiable)
• Isolated Context: Separate context windows prevent pollution
• No Overlap: Verify zero responsibility overlap with existing agents

Description

• Write clear description: "When this agent should be invoked" in frontmatter
• Include triggering scenarios and conditions

Domain Expertise

• Include relevant domain knowledge (e.g., IOTA SDK patterns)
• Document file-type mandates and boundaries
• Specify exact file patterns the agent handles

Model Selection

Agents can specify which model to use:

Best Practice: Use inherit (default) or explicitly set sonnet. Sonnet provides excellent performance for nearly all agent tasks. Only use opus for exceptionally complex reasoning tasks, or haiku for trivial operations.

Tool Permissions

Recommended patterns:

• ✅ Read(/path/to/module/**) - Restrict to specific paths
• ✅ Bash(go test:*), Bash(go vet:*) - Specific patterns
• ✅ Tool inheritance when appropriate

Security risks:

• ❌ Bash(*) - Never grant unrestricted access
• ❌ Read without path restriction - Overly permissive

Built-in Agents

Note: general-purpose is a built-in agent type provided by Claude Code. It does not need to be defined in .claude/agents/ and is always available for complex, multi-step tasks.

Examples

Example 1: Focused Module Agent

---
allowed-tools: |
  Read(back/internal/modules/insurance/**), Bash(go test:*), Bash(go vet:*)
description: "Fix failing tests in insurance module only"
---

# Insurance Test Fixer

## Role
Fix failing unit tests in insurance module exclusively.

## When to Use
When `make test` shows insurance module test failures.

## Responsibilities
- Analyze test failures in back/internal/modules/insurance/
- Fix broken tests without changing business logic
- Ensure tests pass with `cd back && go test ./internal/modules/insurance/...`

## Knowledge Base
- Uses IOTA SDK testing patterns (itf.Setup, itf.MockDB)
- Follows table-driven test conventions
- Maintains test isolation and cleanup

Example 2: Repository Agent

---
allowed-tools: |
  Read(back/internal/**/*_repository.go), Read(back/internal/**/*_repository_test.go), Edit, Bash(go test:*)
description: "Manage repository layer: interfaces, implementations, and tests"
---

# Repository Expert

## Role
Create, update, and optimize repository layer code.

## When to Use
- Creating new repository interfaces or implementations
- Optimizing database queries
- Fixing repository-related bugs
- Writing repository tests

## Responsibilities
- Define repository interfaces in domain layer
- Implement repositories in infrastructure/persistence layer
- Write comprehensive repository tests
- Optimize query performance
- Ensure tenant isolation in queries

## Knowledge Base
- IOTA SDK repo patterns (QueryBuilder, filters)
- PostgreSQL query optimization
- Transaction handling with pgx
- Multi-tenant query patterns

Example 3: UI Component Agent

---
allowed-tools: |
  Read(back/internal/modules/**/*_controller.go), Read(back/internal/modules/**/*_viewmodel.go), Read(back/internal/modules/**/*.templ), Edit, Bash(templ generate:*)
description: "Manage UI layer: controllers, view-models, and templates"
---

# UI Editor

## Role
Create and update presentation layer components.

## When to Use
- Creating new pages or forms
- Updating controllers or view-models
- Modifying Templ templates
- Implementing HTMX interactions

## Responsibilities
- Build controllers with proper auth guards
- Create view-models for data transformation
- Write Templ templates using IOTA SDK components
- Implement HTMX workflows
- Handle i18n with translation keys

## Knowledge Base
- IOTA SDK component library (Form, Table, Modal)
- Templ syntax and best practices
- HTMX patterns (hx-get, hx-post, hx-target)
- Alpine.js for client-side reactivity
- Tailwind CSS design system

Performance Considerations

Context Rebuilding Latency:

• Each agent starts with a fresh context window (not shared with main conversation)
• Initial agent invocation has slight latency while context is built
• Subsequent tool calls within same agent are faster
• Trade-off: Isolated context prevents pollution but requires rebuild time

Optimization Tips:

• Group related tasks in single agent invocation rather than multiple short invocations
• Use inherit or sonnet model for best balance of speed and capability
• Design agents with clear, focused responsibilities to minimize context size

Best Practices

1. One Responsibility: Each agent handles exactly one domain
2. Clear Boundaries: Document which files/patterns the agent manages
3. Minimal Permissions: Grant only tools needed for the domain
4. Domain Knowledge: Include patterns, conventions, and best practices
5. Triggering Conditions: Make it clear when to invoke the agent
6. No Overlap: Verify no other agent handles the same files
7. Model Selection: Use inherit or sonnet unless you have specific needs

Quick Reference Examples

Minimal Agent with Restricted Scope

---
allowed-tools: |
  Read(back/internal/modules/insurance/**), Bash(go test:*), Bash(go vet:*)
description: "Fix failing tests in insurance module only"
---

# Insurance Test Fixer

## Role
Fix failing unit tests in insurance module exclusively.

## When to Use
When `make test` shows insurance module test failures.

## Responsibilities
- Analyze test failures in back/internal/modules/insurance/
- Fix broken tests without changing business logic

Key Points:

• Restricted Read path (insurance module only)
• Limited Bash patterns (testing commands only)
• Single responsibility (test fixing)
• Clear triggering condition

Multi-Layer Agent Example

---
allowed-tools: |
  Read(back/**/*_controller.go), Read(back/**/*_viewmodel.go), Read(back/**/*.templ), Edit, Bash(templ generate:*)
description: "Manage presentation layer: controllers, view-models, templates"
---

# UI Editor

## Role
Create and update presentation layer components.

## When to Use
- Creating new pages or forms
- Updating controllers or view-models
- Modifying Templ templates

## Responsibilities
- Build controllers with proper auth guards
- Create view-models for data transformation
- Write Templ templates using IOTA SDK components

## Knowledge Base
- IOTA SDK component library
- Templ syntax and best practices
- HTMX patterns (hx-get, hx-post, hx-target)

Key Points:

• Multiple file patterns (controllers, viewmodels, templates)
• Layer-specific scope (presentation only)
• Domain knowledge included
• Clear file-type mandates

Agent vs Command

Use agents when:

• You need context isolation from the main conversation
• The task requires specialized expertise
• You want parallel execution without interference
• The task involves complex, multi-step workflows

Use commands when:

• You need dynamic context loading at invocation time
• The task is a simple workflow that doesn't need isolation
• You want to extend Claude's interface with custom shortcuts

See .claude/guides/claude-code/commands.md for command creation guidance.