Claude Code Agents

Guide for creating custom agents that provide specialized behaviors and tool access for specific tasks.

When to Use This Skill

Activate this skill when:

• Creating custom agent types for specific workflows

• Defining agent behaviors and tool permissions

• Configuring agent capabilities

• Understanding agent vs skill differences

• Implementing domain-specific agents

What Are Agents?

Agents are specialized Claude instances with:

• Specific tool access: Limited or specialized tool sets

• Defined behaviors: Pre-configured instructions and constraints

• Task focus: Optimized for particular workflows

• Autonomous operation: Can execute multi-step tasks independently

Agents vs Skills

Feature Agents Skills

Activation Explicitly launched via Task tool Auto-activated based on context

Tool Access Configurable, can be restricted Inherit from parent context

State Independent, isolated Share parent context

Use Case Complex multi-step tasks Knowledge and guidelines

Persistence Single execution Always available when loaded

Agent File Structure

Location

Agents are defined in markdown files located in:

• Plugin: <plugin-root>/agents/

• User-level: .claude/agents/

File Naming

• Use kebab-case: code-reviewer.md

• File name becomes the agent type

• Be descriptive about the agent's purpose

Basic Agent Format

name: code-reviewer description: Reviews code for quality and best practices tools: Read, Grep, Glob model: sonnet

You are a code reviewer. Analyze code for quality, security, and best practices.

Workflow

1. Find files: Glob to locate target files
2. Read code: Examine contents
3. Check patterns: Grep for anti-patterns
4. Report: Provide prioritized feedback

Guidelines

• Specific: Reference file:line locations
• Actionable: Suggest concrete fixes
• Prioritized: Critical issues first

Agent Writing Style

Effective agents use direct, imperative language:

Opening Statement

• Do: "You are a [role]. Your role is to [primary function]."

• Don't: "I am a specialized [role] focused on..."

Workflow Steps

• Do: Numbered steps with specific commands

• Don't: Bullet lists describing capabilities

Guidelines Section

• Do: Single-word bold labels with brief explanations

• Don't: Verbose explanations of best practices

Agent Configuration

YAML Frontmatter

Required and optional fields:

name: agent-name # Required: kebab-case identifier description: Brief description # Required: What this agent does tools: # Optional: Tool allowlist

• Read
• Write
• Bash model: sonnet # Optional: Model to use (sonnet, opus, haiku) max_iterations: 10 # Optional: Maximum task iterations timeout: 300 # Optional: Timeout in seconds

Tool Allowlist

Restrict agent to specific tools:

• Can read files

• Can search code

• Can find files

• Cannot use Write, Edit, Bash, etc.

Example:

tools: Read, Grep, Glob

No tool restrictions (access to all tools):

Omit tools field entirely

Model Selection

Choose appropriate model for the task:

model: haiku # Fast, cost-effective for simple tasks

model: sonnet # Balanced (default)

model: opus # Most capable for complex tasks

Common Agent Patterns

Read-Only Analysis Agent

For security scans, code reviews, or audits. Restricted to Read, Grep, Glob.

See: templates/read-only-analyzer.md

Write-Capable Agent

For generating tests, documentation, or code. Includes Write tool.

See: templates/write-capable-agent.md

Full-Access Agent

For refactoring, migrations, or complex modifications. Omit tools field entirely for no restrictions.

See: templates/full-access-agent.md

MCP-Enabled Agent

For browser automation, external APIs, or specialized MCP server tools. Mix core tools with MCP tools.

See: templates/mcp-agent.md

Agent Plugin Configuration

In plugin.json

{ "agents": [ "./agents/code-reviewer.md", "./agents/test-generator.md", "./agents/security-analyzer.md" ] }

Directory-Based Loading

{ "agents": "./agents" }

Loads all .md files in agents/ directory.

Invoking Agents

Agents are launched via the Task tool:

In parent Claude conversation

Task( subagent_type="code-reviewer", description="Review authentication module", prompt=""" Review the authentication module for: - Security vulnerabilities - Error handling - Input validation - Best practices """ )

Agent Communication

Input to Agent

• Task description

• Detailed prompt

• Access to conversation history (if configured)

Output from Agent

• Final report/result

• No ongoing dialogue

• One-time execution

Best Practices

Clear Purpose

Each agent should have a specific, well-defined purpose:

name: migration-helper description: Assists with database schema migrations

Database Migration Agent

Specialized in creating and validating database migrations.

Appropriate Tool Access

Only grant necessary tools:

Analysis agent - read-only

tools: Read, Grep, Glob

Implementation agent - can modify

tools: Read, Write, Edit, Glob, Grep

Model Selection

Match model to task complexity:

• haiku: Simple, repetitive tasks

• sonnet: Standard tasks (default)

• opus: Complex reasoning required

Iteration Limits

Set appropriate limits for task complexity:

max_iterations: 5 # Simple, focused task

max_iterations: 20 # Complex, multi-step workflow

Clear Instructions

Provide explicit behavior guidelines:

Testing Agent

Mandatory Requirements

• Generate tests for ALL public methods
• Achieve minimum 80% code coverage
• Include edge cases and error scenarios
• Use project's testing framework conventions

Constraints

• Do not modify source code
• Follow existing test file naming patterns
• Use appropriate assertions

Security Considerations

Tool Restrictions

Limit dangerous operations:

Don't give Bash access to untrusted agents

tools:

• Read
• Write # Safer than arbitrary shell commands

Input Validation

Validate agent inputs:

Deployment Agent

Before deploying:

1. Verify target environment is valid
2. Check deployment permissions
3. Validate configuration
4. Confirm destructive operations

Sensitive Data

Never hardcode:

• Credentials

• API keys

• Private URLs

• Access tokens

Agent Examples

For complete, production-ready agent templates:

• templates/basic-agent.md

• Official minimal example

• templates/read-only-analyzer.md

• Security analyzer pattern

• templates/write-capable-agent.md

• Test generator pattern

• templates/full-access-agent.md

• Refactoring pattern (no tool restrictions)

• templates/mcp-agent.md

• Browser testing with MCP tools

Troubleshooting

Agent Not Found

• Verify agent file location matches plugin.json

• Check file naming (kebab-case, .md extension)

• Ensure plugin is properly installed

Tool Access Denied

• Check tools allowlist in frontmatter

• Verify tool names match exactly

• Ensure parent context permits delegation

Unexpected Behavior

• Review agent instructions for clarity

• Check model selection appropriateness

• Verify iteration limits aren't too restrictive

• Test with verbose output

References

Templates directory:

• templates/basic-agent.md

• Official minimal example

• templates/read-only-analyzer.md

• Security analysis pattern

• templates/write-capable-agent.md

• Test generation pattern

• templates/full-access-agent.md

• Refactoring pattern (no tool restrictions)

• templates/mcp-agent.md

• MCP tools pattern (browser automation)

Documentation:

• Claude Code Agents: https://code.claude.com/docs/en/agents

• Task Tool: https://code.claude.com/docs/en/tools/task