Agents
The agent roster in depth — every family of specialists, what dispatches each one, and how you direct them.
An agent is a Markdown file. The roster ships in .claude/agents/ under your
install root — 48 definition files, each a readable job description: who the
specialist is, when to use it, which tools it may touch, which model it runs
on, and the full working method in plain prose. There is no compiled agent and
no hidden registry. The file is the agent, and editing it changes behavior on
the very next run.
This page documents the roster by family — what each group of specialists does, when the system reaches for it, and how you interact with it. The flat one-row-per-agent table lives in Catalogs; the ideas behind delegation live in Missions, operations & the fleet.
What an agent definition is
Every file follows the same contract — YAML frontmatter over a prose body:
| Field | What it does |
|---|---|
name | The dispatch name — how sessions and daemons refer to the agent |
description | The when-to-use statement. This is what a dispatching session matches against when picking a specialist |
tools | An exclusive allowlist. Listing tools restricts the agent to exactly those; omitting the line inherits everything. An agent's entire tool reach is visible in one line of its file |
model | A per-agent cost/quality dial — opus for judgment-heavy work, sonnet for mechanical throughput, haiku for the cheapest checks. Change one word to retune |
skills | Optional skills the agent loads for its craft |
memory | Optional — grants the agent its own persistent memory file across runs |
The body below the frontmatter is the agent's method: its workflow, its output contract, its rules. Read any file in the Agents view to see exactly how a specialist thinks — that transparency is deliberate, and it extends to editing: changes are live on the next spawn, with nothing to restart.
A few roster files carry only a comment block instead of full frontmatter. Those are pipeline-only agents: they are never dispatched by name from a session — the automation daemon spawns them directly and they read their own definition as instructions. You will meet them in the intelligence desk and pipeline families below.
The three ways an agent runs
Not every agent runs the same way, and the run surface shapes how you interact with it:
| Surface | What it is | You see it as |
|---|---|---|
| Dispatched specialist | A session hands one bounded job to a roster agent; it works in an isolated context, returns a summary, and ends | The dispatching session reports back; output files land in your workspace |
| Fleet session | A persistent, full-capability agent session in a terminal pane, grounded with a role file and a mission | A live pane in the Terminals view — watch it, type into it, pause it |
| Scheduled or triggered run | The automation daemon spawns a fresh headless session that executes a routine, often as one of these agents | A run entry with a log in the Routines view |
The rule of thumb: bounded and parallel work goes to dispatched specialists, recurring work goes to routines, and long coordinated workstreams become a mission fleet. The routines concept page covers choosing between them.
The mission fleet pair
Two definitions are not dispatched specialists at all — they are role files that ground the fleet:
| Agent | Role |
|---|---|
mission-commander | Runs one mission end to end: reads the dossier, decomposes it into operations, assigns workers, evaluates results against the success conditions, and completes the mission through the gate |
mission-worker | Executes exactly one operation: reads its brief from disk, works it with full platform capabilities, writes durable output into the operation folder, reports done or blocked |
When you dispatch a mission from the Missions Board, the platform stands up one terminal workspace with a commander pane and worker panes; each pane is a full agent session with the matching role file injected as its operating posture. The commander holds the whole picture; each worker sees only its slice. You interact by watching the panes live, typing into any of them, or pausing all agent terminal control with one switch — the fleet is deliberately visible. Full narrative: Missions, operations & the fleet.
Scheduled dispatch
| Agent | Role |
|---|---|
schedule-executor | The agent behind every Calendar entry that dispatches one |
This is the roster member you meet without asking for it. When a scheduled
entry comes due, the platform writes that firing a dispatch brief — the
instruction, the grounding it needs, the mission it relates to, where its
report goes, and the autonomy level it works under — and schedule-executor
reads the brief and does the work. It has two modes, stated in the brief's
header: execute (a scheduled entry has come due) and configure (you
sketched intent over the week and it turns that into real entries).
It runs either headless, writing a report file you read afterward, or in a grounded terminal workspace you can watch live — the entry chooses. The autonomy level it carries is the one on the entry; what each level permits is on Autonomy and controls.
Research & audit
The judgment-heavy specialists. You (or another agent) dispatch them with a question or a target; they return a report — usually a dated Markdown file in your documents tree, tagged with the agent's two-letter author code in the filename.
| Agent | Model | What it does |
|---|---|---|
deep-researcher | Opus | Multi-phase research on any topic — multi-source, cited, produces a structured report file |
quick-researcher | Sonnet | Focused lightweight research — a handful of sources, returns findings as text rather than a report |
deepdive-author | Opus | A verbose, primary-source deep-dive on a feature, subsystem, or codebase, written for a named downstream consumer — the constructive counterpart to an audit |
feature-auditor | Opus | A four-phase production-readiness and correctness audit of any feature — exhaustive reading, workflow tracing, issue identification |
critique-validator | Opus | Adversarial critique of any agent output — plans, reports, decisions — with structured verdicts built to resist tell-you-what-you-want answers |
professor-gemini | Opus | Domain expert for Google Cloud and Gemini integrations — API verification, migration advice, curated documentation |
When the system dispatches them: a session facing a research-shaped or audit-shaped task matches it against these descriptions and fans work out — several researchers can run in parallel on independent questions. When you dispatch them: ask for the audit or the research in any session; the reports land on disk where you (and later sessions) can read them.
Engineering
| Agent | Model | What it does |
|---|---|---|
feature-developer | Opus | Full-stack implementation — routes, services, components, stores, migrations — following the existing patterns of whatever codebase it works in |
refactorer | Sonnet | Behavior-preserving cleanup: deduplication, better abstractions, pattern alignment |
dependency-checker | Haiku | Outdated packages, known vulnerabilities, license compliance — read-only by design |
These are the workhorses for parallel bounded coding jobs: a session splits a build into scoped pieces and dispatches one developer per piece. The auditor and critique agents above pair naturally as the review step.
Knowledge, context & memory
The specialists that maintain the platform's own knowledge layers:
| Agent | Model | What it does |
|---|---|---|
context-architect | Opus | Queries every memory and knowledge layer for a task, then composes a context artifact — the grounding package a new agent session launches with |
kg-ingester | Sonnet | Reads documents and extracts entities and relationships into the knowledge graph using its own reasoning — no external extraction service, no per-document API cost |
doc-organizer | Sonnet | Manages the document lifecycle — files completed reports into the right folders, enforces naming, archives stale material |
You rarely dispatch these directly. The graph's Enrich action dispatches the ingester; housekeeping routines dispatch the organizer; the context architect is the one to reach for before a large piece of work, and its output feeds context artifacts.
The products pipeline chain
The chain below turns a pile of source material into a finished two-part knowledge product. Each specialist owns one stage; the Products view drives dispatch and you approve between stages:
product-sighter (survey the sources) → product-composer (propose an
outline) → product-research-scout + product-researcher (plan, then extract
section knowledge) → product-consolidator (merge research notes) →
product-auditor (cross-section overview and audit) → product-scope-refiner
(transform notes into near-final sections) → product-section-finalizer
(final polish) → product-human-author (the human-facing manual) — with
product-illustrator composing the cover.
Two earlier-generation files remain on disk beside the chain. product-scout
is retired outright — its own header says so, and nothing dispatches it.
product-draft is the previous drafting stage, superseded by the refine and
finalize pair above; the Products view no longer dispatches it, but its routine
and the products tools still can. Both are readable, and neither is in the path
the view drives. The full chain, its handoff artifacts, and where your
approvals sit are covered in Agent pipelines.
The video pipelines
Two three-agent chains — one per rendering engine — plus a clip-preparation specialist:
| Agent | Pipeline | Stage |
|---|---|---|
video-brief-author | Remotion | Enriches your freeform brief with creative direction — metaphor, color arc, key moments |
video-script-author | Remotion | Writes the scene-by-scene production script and picks compositions |
video-composer | Remotion | Produces the machine-readable render proposal plus a readable walkthrough for your review |
hyperframes-brief-author | HyperFrames | Rewrites the brief into a denser, reference-aware version |
hyperframes-planner | HyperFrames | Authors the storyboard — per-beat direction, exact block picks, install list |
hyperframes-html-author | HyperFrames | Writes all composition HTML, installs the planned blocks, lints and fixes before finishing |
footage-editor | Either | Prepares one raw clip per instruction — transcribe, cut fillers and silence, grade, trim — producing a clean asset for either pipeline |
Each trio deliberately narrows knowledge per stage: the brief authors know capability categories, the middle agents know the catalog by name, and only the final agent holds the deep authoring surface. You review between every stage in the Video view, and nothing renders until you dispatch it. Stage order and handoffs: Agent pipelines.
The intelligence desk
The writers and analysts behind the news pipeline. Most are pipeline-only agents — the automation daemon dispatches them on schedule or on your trigger, never by name from a chat session:
| Agent | What it does |
|---|---|
observer-agent | Digests batches of harvested news items into observer reports — summarize, categorize, score |
news-scout | Proposes briefing-worthy story clusters from the report pool; one writer run is spawned per cluster |
news-writer | Writes one source-grounded 200–400 word briefing per cluster, with impact metadata |
breaking-writer | Extracts short time-sensitive ticker items from fresh reports, deduplicated against the last 72 hours |
report-scout + report-writer | The deep-dive tier — the scout proposes report candidates, the writer produces typed long-form intelligence reports |
roundup-writer | One weekly multi-topic roundup from the week's material |
newsletter-writer | Curates a bilingual email digest — always as a draft; sending is a separate, explicit human action |
news-translator | Produces native-quality translations of published articles into your configured locales |
news-illustrator | Composes editorial hero-image prompts for fresh articles; the local image daemon renders them |
yt-video-analyzer | Deep 8-section analysis of a harvested video from its transcript, keyframes, and metadata |
You direct this family through the intelligence views: configure sources, enable the routines that schedule the writers, review what they produce, and approve anything outbound. The fan-out shape — scouts propose, the daemon validates and spawns one clean-context writer per item — is explained in Agent pipelines.
Support
| Agent | Model | What it does |
|---|---|---|
support-email | Opus | Works the support inbox queue — reads new mail, classifies it, pulls context from the knowledge base, drafts a reply, and stages it for your approval |
How the approval gate actually works. The shipped default is that the
agent's replies wait for you: the draft lands in Email ▸ Agent and nothing goes
out until you approve it. That is a default, not a law of the product.
email.auto_approve_drafts is a standing authorization under which a
reply-disposition draft that passed the agent's own confidence gate sends
immediately; everything else still takes the per-message path. It ships off.
⚠ It is not the only switch, and this agent is not the only email agent. Each
email routine carries its own Auto-send setting, and the routine's setting wins
over the global one — so the global default being off is not by itself proof
that nothing will send. features/email.mdx covers the full model, including
which shipped routine carries auto-send in its own configuration. Above all of
them sits the Email sending control plane, which refuses every send while it
is off.
The whole model — what a dispatched agent may do unattended, which switch stops each outward action, and what is recorded — is stated once, on Autonomy and controls.
Working with the roster
- Inspect and edit in the Agents view. Every definition opens as an editable file grouped by category. What you read is exactly what the agent executes.
- Clone before you write from scratch. The Create and Clone dialogs prefill frontmatter — name, model, description, a tool picker grouped by server, a skills selector — from any existing agent. The shipped roster is a set of proven templates, not a fixed menu.
- Or just drop a file. A new
.mdin.claude/agents/with valid frontmatter is a new agent. No registration, no build, no restart. - Curate tools deliberately. A narrow
tools:line makes an agent safer, cheaper, and more predictable. Give an agent only what its job needs. - Match the model to the stakes. Judgment work earns
opus; mechanical volume runs onsonnetorhaiku. It is a one-word edit per agent. - Know the author codes. Report-producing agents sign their output files
with a two-letter code in the filename (for example
_dr_for the deep researcher), so you can always tell which specialist wrote what you are reading.
Where to go next
- Agent pipelines — the multi-agent chains stage by stage
- Catalogs — the flat roster table
- Skills — the packaged expertise agents load
- Routines — the scheduled runs many of these agents execute
- Missions, operations & the fleet — the coordination model above the roster