What are Agents?

Agents are markdown files that define subagent configurations — the model to use, which tools they have access to, and their system prompt (persona). They're stored in .claude/agents/ directories.

When the main Claude session needs to delegate work, it spawns these subagents as focused, constrained workers via the Task() tool.

The Three Layers

Every agent is defined by three layers:

1. tools = what the agent can do (hard boundary, enforced by the system)
2. System prompt (markdown body) = what the agent should do (soft guidance)
3. model = how well the agent does it

The constraint is what makes agents effective. A security scanner with every tool available has no focus. A security scanner limited to Read, Glob, Grep with a sharp persona produces much better results.

Agent Parameters

Personas — The System Prompt

The markdown body below the YAML frontmatter acts as the system prompt — the persona. This fundamentally changes what the model pays attention to, what tools it reaches for, and how it structures its analysis.

Give the same codebase to a "security auditor" persona and a "UX copywriter" persona, and they'll produce meaningfully different output. Same model, same code, completely different results.

---
name: security-scanner
description: Scans code for security vulnerabilities
model: opus
tools: Read, Glob, Grep
---
 
You are a senior security engineer reviewing code for vulnerabilities.
Focus on: XSS, injection, exposed secrets, insecure protocols.
Rate each finding 0-100 confidence. Only report findings ≥80.

Persona Design Patterns

The Specialist

Focused on one domain. Ignores everything else.

You are an accessibility specialist. Your only job is to find
WCAG 2.1 AA violations. Ignore code quality, performance, and
architecture. Report only accessibility issues.

The Constrained Reporter

Produces structured output in a specific format.

You are a code reviewer. For each finding, output exactly:
- **File**: path
- **Line**: number
- **Severity**: low/medium/high/critical
- **Confidence**: 0-100
Do not include explanations. Do not suggest fixes.

The Opinionated Expert

Has strong preferences and justifies them.

You are a senior React developer who strongly prefers:
- Server Components over client components
- Composition over inheritance
When reviewing, explain WHY your recommendation is better.

Agent Design Patterns

Read-Only Scout

tools: Read, Glob, Grep

Can examine code but can't change anything. Safe to run in parallel — no conflict risk.

Focused Fixer

tools: Read, Glob, Grep, Edit, Write
maxTurns: 10

Has write access but limited turns. Gets a precise brief, makes one change, reports back.

Speed Runner

model: haiku
tools: Read, Glob, Grep, Bash
maxTurns: 5

Uses the cheapest, fastest model. Good for mechanical tasks like running tests or format checks — not deep reasoning.

Agent Memory

The memory: project field means the agent builds persistent knowledge from previous runs:

.claude/agent-memory/code-fix-scout/
  └── memory.md  ← "Last review found missing error handling on Apollo queries"

This memory gets injected into the agent's system prompt on future runs. Over time, agents become more precise and focused on your specific codebase patterns.

How Agents Get Dispatched

Agents are dispatched by commands or the main session using the Task() tool:

Launch 4 scouts in parallel:
- Scout 1 focuses on logic errors
- Scout 2 focuses on async issues
- Scout 3 focuses on security
- Scout 4 focuses on error handling

Each scout gets its own context window, runs independently, and returns a report to the parent.

Agent Teams (Experimental)

Beyond standard subagents, Claude Code has an experimental feature called Agent Teams — full independent Claude instances that run simultaneously and communicate directly with each other:

• Shared task list at ~/.claude/tasks/{team-name}/
• Direct messaging between teammates
• Self-coordinating without a parent orchestrator

graph TD
  A1[Agent 1] <-->|message| A2[Agent 2]
  A2 <-->|message| A3[Agent 3]
  A1 <-->|message| A3
  TL[Shared Task List] --- A1
  TL --- A2
  TL --- A3

This is different from standard subagents (which only report to a parent). Agent Teams can discuss, debate, and divide work amongst themselves — useful for complex work where inter-agent collaboration genuinely adds value.

Cost Awareness

Agents are where costs can escalate quickly:

• Each agent is a separate API call. 4 parallel scouts = 4× the cost of a single request.
• Opus agents cost ~15× more than Sonnet for the same task. Use Opus only for deep reasoning (security analysis, architectural review). Use Sonnet for most work. Use Haiku for mechanical tasks.
• maxTurns is your cost cap. An agent with maxTurns: 50 can make 50 API calls. Set it to the minimum needed — a focused fixer rarely needs more than 10.
• Read-only scouts are cheap. They don't create follow-up work. Fixers cost more because edits trigger re-reads and verification.

Key Takeaway

Agents are the "hands" of the system. Their power comes from the combination of tools (capability), persona (focus), and model (quality). Commands orchestrate; agents execute. Memory makes them learn over time. Start simple and constrained — you can always add capability later.