claude-agents

Claude Code Agents

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

When spawning as part of a team

Invoke /core:agent-loop for the 4-phase / 6-tier execution model. Invoke /claude-code:claude-teams if the agent joins a multi-agent team. Invoke /core:anti-fabrication always — every claim about a tool, file, or test result requires tool execution.

Glob patterns like /core:* do not expand in Agent prompts. List skill names explicitly.

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 Agent 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

Complete field reference (source: https://code.claude.com/docs/en/sub-agents):

Field	Required	Meaning
name	yes	Unique identifier, lowercase letters and hyphens. Hooks receive this value as agent_type. The filename does not need to match.
description	yes	When Claude delegates to this subagent.
tools	no	Tool allowlist. Omit to inherit all tools. To preload skill content use skills — never list Skill here.
disallowedTools	no	Denylist removed from the inherited or specified tool set.
model	no	sonnet, opus, haiku, fable, a full model ID (e.g. claude-opus-4-8), or inherit. Defaults to inherit.
permissionMode	no	default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual (alias of default, v2.1.200+). Ignored for plugin subagents.
maxTurns	no	Maximum agentic turns before the subagent stops.
skills	no	Skills preloaded into context at startup. See Preloading Skills below.
mcpServers	no	MCP servers available to this subagent (name reference or inline config). Ignored for plugin subagents.
hooks	no	Lifecycle hooks scoped to this subagent. Ignored for plugin subagents.
memory	no	Persistent memory scope: user, project, or local.
background	no	true forces background execution. Unset lets Claude choose; defaults to background as of v2.1.198.
effort	no	low, medium, high, xhigh, or max (model-dependent).
isolation	no	worktree runs the subagent in a temporary git worktree, auto-cleaned if the subagent makes no changes.
color	no	red, blue, green, yellow, purple, orange, pink, cyan.
initialPrompt	no	Auto-submitted first user turn when run as a main-session agent (--agent).

Example:

---
name: agent-name                    # Required: kebab-case identifier
description: Brief description      # Required: What this agent does
tools:                             # Optional: tool allowlist, inherits all if omitted
  - Read
  - Write
  - Bash
model: sonnet                      # Optional: model to use, defaults to inherit
---

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 the model for the task, or inherit the parent session's model:

---
model: haiku               # Fast, cost-effective for simple tasks
# model: sonnet            # Balanced
# model: opus              # Complex reasoning
# model: fable             # Fable 5 tier
# model: claude-opus-4-8   # Full model ID pins an exact version
# model: inherit           # Default — matches the parent session's model
---

Preloading Skills

The skills field preloads full skill content into the subagent's context at startup — not just the description shown during discovery. Use the namespaced form for plugin skills:

---
name: phoenix-reviewer
description: Reviews Phoenix application code
tools: Read, Glob, Grep
skills:
  - elixir:phoenix
  - elixir:testing
---

Skills not listed in skills remain invocable through the Skill tool during the run — skills only controls what loads automatically at startup. Never list Skill in tools: to enable this; skills is the dedicated field.

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 Agent tool (Task remains a deprecated alias, renamed in v2.1.63):

# In parent Claude conversation
Agent(
    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 has 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
• opus / fable: Complex reasoning required
• inherit: Default when model is omitted — matches the parent session

Turn Limits

Set maxTurns for task complexity:

---
maxTurns: 5    # Simple, focused task
# maxTurns: 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
• Subagents (Agent Tool): https://code.claude.com/docs/en/sub-agents