Claude agents, explained

What's an AI agent (for real)

An AI agent is a program where an LLM decides what actions to take — which tools to call, in what order, and when to stop. The LLM is the brain; the "tools" are functions it can call (read a file, search the web, run a command, query an API).

Strip the hype: an agent is a loop that keeps asking the LLM what to do next, calls the tools the LLM picks, feeds results back in, and repeats until the LLM says "done."

The three Claude agent flavors

Skills vs Subagents — same format, different jobs

Both Skills and Subagents are markdown files Claude Code loads from your .claude/ folder. Both define what Claude does using a YAML frontmatter + instructions. The confusion is real — the practical difference is what they're for.

Concrete example: if you write PR descriptions every day, install the pr-description-writer skill — Claude will use it inline whenever you ask. If you do a giant code review that pulls in 30 files of context, spawn a code-reviewer subagent — it reads everything in a separate window and reports back "5 issues, here they are." Your main session stays clean.

How to actually use them

---
name: code-reviewer
description: Use when reviewing a diff or PR. Spawns a focused reviewer that reads files independently and reports issues.
tools: [Read, Glob, Grep]
---

You are a senior code reviewer. Read the diff carefully and look for:
- Logic bugs
- Edge cases not handled
- Security issues
- Test coverage gaps

Report back with at most 5 most important issues, each with:
- file:line
- the problem
- a suggested fix

Skip nitpicks (formatting, naming preferences). Focus on what actually matters.

pip install claude-agent-sdk
# or: npm install @anthropic-ai/claude-agent-sdk

export ANTHROPIC_API_KEY=your-key

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

curl https://api.anthropic.com/v1/agents/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "agent_id": "research-assistant",
    "input": "What changed in the EU AI Act this month?"
  }'

Decision matrix — which one do you actually need?

When agents are overkill

• ✗You can solve the problem with a single LLM call. Don't loop if you don't need to loop.
• ✗The task has a known, fixed sequence of steps. That's a workflow — write it as code that calls the LLM at specific points.
• ✗You can't articulate what "done" looks like. Agents need a stop condition. If you can't define one, the agent will spin and burn tokens.
• ✗Latency matters. Agent loops are slow by definition — multiple LLM calls, often serial. For real-time UX, use a single call.
• ✗It's a recurring small task in Claude Code. That's a Skill, not an agent.

Where to find ready-made agents

Terms worth knowing

The agent space has its own vocabulary. Plain-English definitions for the terms that come up most: