Claude Code Agents

---
name: claude-code-agents
description: Create and configure Claude Code agents with YAML frontmatter, tool selection, model specification, and naming conventions. Reference for building specialized AI subagents that handle complex, multi-step tasks.
---

# Claude Code Agents — Meta Reference

This skill provides the definitive reference for creating Claude Code agents. Use this when building new agents or understanding agent architecture.

---

## Quick Reference

| Field | Purpose | Required |
|-------|---------|----------|
| `name` | Agent identifier (kebab-case) | Yes |
| `description` | When to invoke this agent | Yes |
| `tools` | Allowed tool list | No (defaults: all) |
| `disallowedTools` | Tools to explicitly deny | No |
| `model` | Claude model variant | No (default: inherit) |
| `permissionMode` | Permission handling mode | No (default: default) |
| `skills` | Skills to preload into context | No |
| `hooks` | Lifecycle hooks (PreToolUse, PostToolUse, Stop) | No |

## Agent Structure

```text
.claude/agents/
├── code-reviewer.md
├── security-auditor.md
├── test-architect.md
└── system-architect.md
```

---

## Built-in Subagents

Claude Code includes built-in subagents that Claude automatically uses when appropriate:

| Subagent | Model | Tools | Purpose |
|----------|-------|-------|---------|
| **Explore** | haiku | Read-only | Fast codebase search, file discovery, code analysis |
| **Plan** | inherit | Read-only | Research and gather context during plan mode |
| **general-purpose** | inherit | All | Complex multi-step tasks requiring exploration and action |
| **Bash** | inherit | Bash | Terminal commands in separate context |
| **statusline-setup** | sonnet | - | `/statusline` configuration |
| **Claude Code Guide** | haiku | - | Answer feature questions |

Built-in subagents inherit parent conversation permissions with additional tool restrictions. They cannot spawn other subagents (prevents infinite nesting).

---

## Agent Template

```markdown
---
name: agent-name
description: When to use this agent (single line)
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Agent Name

You are a [role description].

## Responsibilities

- Responsibility 1
- Responsibility 2
- Responsibility 3

## Workflow

1. Step 1: [action]
2. Step 2: [action]
3. Step 3: [action]

## Output Format

[Specify expected output structure]
```

---

## Frontmatter Specification

### name (required)

```yaml
name: security-auditor
```

**Rules**:
- Kebab-case only
- Match filename (without .md)
- Descriptive but concise

### description (required)

```yaml
description: Analyze code for security vulnerabilities using OWASP Top 10
```

**Rules**:
- Single line, under 200 characters
- Explain WHEN Claude should invoke this agent
- Include key capabilities

### tools (optional)

```yaml
tools: Read, Grep, Glob, Bash, Edit, Write
```

**Available tools**:
| Tool | Purpose | Use When |
|------|---------|----------|
| `Read` | Read files | Always include |
| `Grep` | Search content | Code analysis |
| `Glob` | Find files | File discovery |
| `Bash` | Run commands | Build, test, git |
| `Edit` | Modify files | Code changes |
| `Write` | Create files | New files |
| `WebFetch` | Fetch URLs | Documentation lookup |
| `WebSearch` | Search web | Research tasks |
| `Task` | Spawn subagents | Delegation |

**Minimal permissions principle**: Only include tools the agent needs.

### model (optional)

```yaml
model: sonnet  # or opus, haiku, inherit
```

| Model | Use For | Cost |
|-------|---------|------|
| `haiku` | Simple, fast tasks | Low |
| `sonnet` | Most tasks | Medium |
| `opus` | Complex reasoning | High |
| `inherit` | Same as parent (default) | Varies |

### permissionMode (optional)

```yaml
permissionMode: dontAsk
```

| Mode | Behavior |
|------|----------|
| `default` | Standard permission checking with prompts |
| `acceptEdits` | Auto-accept file edits |
| `dontAsk` | Auto-deny permission prompts |
| `bypassPermissions` | Skip all checks (use cautiously) |
| `plan` | Read-only exploration mode |

### skills (optional)

Preload skills into subagent context at startup:

```yaml
skills:
  - api-conventions
  - error-handling-patterns
```

Full skill content is injected into the subagent's context.

### hooks (optional)

Add lifecycle hooks directly to agent frontmatter:

```yaml
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-query.sh"
```

Hook receives JSON via stdin with `tool_input`. Exit code 2 blocks the operation.

---

## Agent Categories

### Analysis Agents (Read-only)

```yaml
tools: Read, Grep, Glob
```

Examples:
- `code-reviewer` - Review code quality
- `security-auditor` - Find vulnerabilities
- `architecture-analyzer` - Analyze system design

### Implementation Agents (Read-write)

```yaml
tools: Read, Grep, Glob, Edit, Write, Bash
```

Examples:
- `backend-engineer` - Build APIs
- `frontend-engineer` - Build UIs
- `test-engineer` - Write tests

### Research Agents (Web access)

```yaml
tools: Read, WebFetch, WebSearch
```

Examples:
- `documentation-researcher` - Find docs
- `technology-scout` - Evaluate options

---

## Agent Design Patterns

### Single-Responsibility Agent

```markdown
---
name: sql-optimizer
description: Analyze and optimize SQL queries for performance
tools: Read, Grep, Glob
model: sonnet
---

# SQL Optimizer

You optimize SQL queries. Focus on:

1. Index usage analysis
2. Query plan examination
3. Performance recommendations

Output optimization suggestions with before/after examples.
```

### Orchestrator Agent

```markdown
---
name: fullstack-builder
description: Coordinate frontend, backend, and database changes
tools: Read, Grep, Glob, Task
model: sonnet
---

# Fullstack Builder

You coordinate multi-layer changes by delegating to specialized agents:

1. Analyze requirements
2. Delegate database changes to sql-engineer
3. Delegate API changes to backend-engineer
4. Delegate UI changes to frontend-engineer
5. Verify integration
```

### Verification Agent

```markdown
---
name: pre-commit-checker
description: Verify code quality before commits
tools: Read, Grep, Bash
model: haiku
---

# Pre-Commit Checker

Run quality checks:
- [ ] Linting passes
- [ ] Tests pass
- [ ] No console.logs
- [ ] No TODO comments
- [ ] Types correct

Return PASS or FAIL with details.
```

---

## Agent ↔ Skill Relationship

**Agents** do work → **Skills** provide knowledge

```text
Agent: backend-engineer
  ├── Uses skill: software-backend (API patterns)
  ├── Uses skill: dev-api-design (REST/GraphQL)
  └── Uses skill: data-sql-optimization (query optimization)
```

Agents reference skills implicitly—Claude loads relevant skill content based on context.

---

## Naming Conventions

| Pattern | Example | Use For |
|---------|---------|---------|
| `{role}` | `code-reviewer` | General role |
| `{domain}-{role}` | `security-auditor` | Domain-specific |
| `{action}-{target}` | `test-generator` | Action-focused |
| `{tech}-{role}` | `typescript-migrator` | Tech-specific |

---

## Invocation Patterns

### Direct (user triggers)

```
User: "Review this code for security issues"
Claude: [invokes security-auditor agent]
```

### Via Command

```markdown
<!-- .claude/commands/security.md -->
Run security analysis using the security-auditor agent.
```

### Via Another Agent

```yaml
# Parent agent
tools: Task  # Can spawn subagents
```

---

## Quality Checklist

```text
AGENT VALIDATION CHECKLIST

Frontmatter:
[ ] name matches filename (kebab-case)
[ ] description explains when to invoke
[ ] tools are minimal necessary
[ ] model appropriate for task complexity

Content:
[ ] Clear role definition
[ ] Specific responsibilities listed
[ ] Workflow steps defined
[ ] Output format specified

Integration:
[ ] Related skills identified
[ ] Commands reference this agent (if applicable)
```

---

## When to Use Subagents

### Use Subagents When

- Tasks produce verbose output you don't need in main context
- You want to enforce specific tool restrictions
- Work is self-contained with a clear summary
- Tasks are parallelizable (run multiple agents concurrently)
- You need isolated context to preserve main conversation quality

### Use Main Conversation When

- Task needs frequent back-and-forth iteration
- Multiple phases share significant context
- Latency matters (subagents start fresh)
- You need real-time feedback during execution

### Execution Modes

**Foreground** (default): Blocks main conversation, passes permission prompts through.

**Background** (Ctrl+B): Concurrent execution, auto-denies unpre-approved permissions, MCP tools unavailable.

### Session Resumption

Continue previous subagent work without restarting:

```text
User: Use the code-reviewer subagent to review the authentication module
[Agent completes]

User: Continue that code review and analyze authorization logic
[Resumes previous subagent context]
```

---

## Security Best Practices

### Deny-All Default

Start with no tools, add only what's needed:

```yaml
# Reviewer: read-only
tools: Read, Grep, Glob

# Builder: add write access
tools: Read, Grep, Glob, Edit, Write, Bash
```

### Dangerous Command Awareness

Require explicit confirmation for:
- `rm -rf` — Recursive delete
- `git push --force` — Overwrite history
- `sudo` — Elevated permissions
- `DROP TABLE` — Database destruction
- Infrastructure changes (Terraform, K8s)

### Context Isolation

- Each subagent has isolated context window
- Orchestrator maintains global state (compact)
- Use CLAUDE.md for shared conventions
- Never pass full codebase to subagents

---

## Advanced Features (2.1.0+)

### Wildcard Tool Permissions

Define broader permission patterns with fewer rules:

```yaml
tools: Bash(npm *), Bash(*-h*), Read, Grep
```

Examples:
- `Bash(npm *)` — Allow all npm commands
- `Bash(*-h*)` — Allow help flags
- `Bash(git status)` — Allow specific command

### Agent Creation Methods

**1. Interactive CLI** (recommended):

```bash
/agents
```

**2. Manual file creation** in `.claude/agents/` (project) or `~/.claude/agents/` (user)

**3. CLI flag** (session-only):

```bash
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'
```

### Agents Continue After Permission Denial

Subagents now try alternative approaches rather than stopping when permissions are denied, making autonomous workflows more resilient.

---

## Navigation

**Resources**
- [references/agent-patterns.md](references/agent-patterns.md) — Common agent patterns
- [references/agent-tools.md](references/agent-tools.md) — Tool capabilities reference
- [data/sources.json](data/sources.json) — Official documentation links

**Related Skills**
- [../claude-code-skills/SKILL.md](../claude-code-skills/SKILL.md) — Skill creation
- [../claude-code-commands/SKILL.md](../claude-code-commands/SKILL.md) — Command creation
- [../claude-code-hooks/SKILL.md](../claude-code-hooks/SKILL.md) — Hook automation