Agents

What is an agent?

An agent is a specialized Claude Code subprocess. It has its own context window, its own set of allowed tools, and an optional system prompt that defines how it behaves. It runs in isolation from the main conversation — it does not share history, state, or tool access with the process that spawned it.

Claude Code itself is an agent. When you open a session and type a prompt, you are talking to the main agent. That main agent can then spawn sub-agents to handle specific delegated work.

Three things define an agent:

• A name and description that tell Claude when and why to invoke it
• A list of tools it is allowed to use
• An optional system prompt that shapes its focus and constraints

Agents are stored as Markdown files in .claude/agents/. They live alongside your CLAUDE.md and custom commands, under version control, as part of your project.

The main reason to use agents is parallelism. The main Claude Code process can spawn multiple sub-agents simultaneously, each working independently on a separate task. When they finish, results come back to the main process. For work that is naturally decomposable — running tests while generating documentation, checking multiple data schemas at once — this is a significant speedup over sequential prompting.

How are agents activated?

Agents are activated in three ways.

Automatically: Claude Code reads the description field of every agent in .claude/agents/ and uses it to decide whether a given task should be delegated. When a user prompt or an in-session task matches an agent’s description closely enough, Claude spawns it without being explicitly told to.

By name in natural language: You can write “use the test-runner agent” in your prompt. Claude decides whether to delegate — it is a suggestion, not a guarantee.

By @-mention: Type @ and pick the agent from the typeahead (the same way you @-mention files). This guarantees that specific agent runs, regardless of what Claude would otherwise decide.

@"test-runner (agent)" check the auth module changes

You can also type the mention manually without the picker: @agent-test-runner. The @-mention controls which agent Claude invokes — your full message still goes to Claude, which writes the agent’s task prompt based on what you asked.

direction: right

user: User prompt
main: Claude Code
a: Agent A
b: Agent B
results: Results merged
response: Response

user -> main
main -> a
main -> b
a -> results
b -> results
results -> main
main -> response

Parallelism is what makes agents distinct from commands and skills. If two tasks are independent — running the test suite and updating docstrings, for example — there is no reason to wait for one before starting the other. Agents make that possible.

Because Claude decides when to auto-invoke based on the description, writing a precise description is one of the most important parts of defining an agent. A vague description means Claude either over-invokes it or ignores it. A specific description (“run the test suite and report failures — invoke after any code change”) leaves no ambiguity.

Skill vs agent

This is the distinction that confuses most people when they first encounter agents.

The clearest one-sentence summary: a skill tells the current Claude what to do; an agent is a separate Claude that goes off and does it.

Use a skill when you want to standardize how you interact with Claude in a session. Use an agent when you want Claude to delegate a task to another process entirely, run it in isolation, and bring the results back.

For DS/ML work, the line often falls here: a skill might format your prompt for running an experiment or summarize a training log. An agent would run the validation suite against a new dataset, or generate documentation for a module you just wrote, while you or another agent continues working on something else.

How to create an agent

Create a Markdown file in .claude/agents/ with a YAML frontmatter block followed by the system prompt in the body. No command required — Claude Code loads any .md file it finds in that directory.

> touch .claude/agents/test-runner.md

Here is a complete, realistic example:

---
name: test-runner
description: Run the test suite and report failures. Invoke after any code change. # [1]
model: sonnet  # [2]
---

You are a focused test runner. Run the project test suite, identify failing  # [3]
tests, and report results clearly. Do not fix bugs — only report what failed
and why.

1. The description drives automatic invocation. Be specific about when this agent should be used.
2. The model field is optional. Omit it to inherit the session default (Sonnet).
3. The markdown body is the agent’s system prompt. Explicitly telling it what not to do (fix bugs) prevents scope creep and keeps the agent focused.

Dos and don’ts