Claude Code Agents

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

Agent Structure

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

Agent Template

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

name: security-auditor

Rules:

• Kebab-case only
• Match filename (without .md)
• Descriptive but concise

description (required)

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)

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

Available tools:

Minimal permissions principle: Only include tools the agent needs.

model (optional)

model: sonnet  # or opus, haiku

Agent Categories

Analysis Agents (Read-only)

tools: Read, Grep, Glob

Examples:

• code-reviewer - Review code quality
• security-auditor - Find vulnerabilities
• architecture-analyzer - Analyze system design

Implementation Agents (Read-write)

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

Examples:

• backend-engineer - Build APIs
• frontend-engineer - Build UIs
• test-engineer - Write tests

Research Agents (Web access)

tools: Read, WebFetch, WebSearch

Examples:

• documentation-researcher - Find docs
• technology-scout - Evaluate options

Agent Design Patterns

Single-Responsibility Agent

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

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

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

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

Invocation Patterns

Direct (user triggers)

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

Via Command

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

Via Another Agent

# Parent agent
tools: Task  # Can spawn subagents

Quality Checklist

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)

Security Best Practices

Deny-All Default

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

# 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

Navigation

Resources

• resources/agent-patterns.md — Common agent patterns
• resources/agent-tools.md — Tool capabilities reference
• data/sources.json — Official documentation links

Related Skills

• ../claude-code-skills/SKILL.md — Skill creation
• ../claude-code-commands/SKILL.md — Command creation
• ../claude-code-hooks/SKILL.md — Hook automation