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)
model	Claude model variant	No (default: sonnet)

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:

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)

model: sonnet  # or opus, haiku

Model	Use For	Cost
haiku	Simple, fast tasks	Low
sonnet	Most tasks (default)	Medium
opus	Complex reasoning	High

---

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

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

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