An Agent is a focused role with a declared identity — one prompt, one model, one purpose — invoked by an orchestrator and producing one artifact per run.

Primitive

Agent

The artifact

A markdown file. Frontmatter declares identity. Body declares behavior.

.claude/agents/builders/builder-product.md

---name: builder-product← identity keydescription: Executes ONE task from product-spec planmodel: sonnet← cost/quality knobtools: [Read, Write, Edit, Bash, Grep, Glob]← minimum set---

# PurposeOne paragraph. Your single job. What you own.

## WorkflowNumbered steps. Read task → act → report.

## ReportExact output contract. Structured, parseable.

The frontmatter IS the agent's boot-time configuration. Every field is load-bearing — missing `name` means nobody can invoke it; missing `tools` means it inherits everything (the opposite of focused).

The levers you control

Every agent has exactly four knobs.

Context

what it reads

System prompt, skills, mental models, briefing docs.

Model

how smart

Haiku / Sonnet / Opus. Per-task, not default.

Prompt

what to do

Task brief from orchestrator. The user message.

Tools

how it acts

Minimum set. Never "all tools just in case."

Every agent failure traces to one of these four being wrong. Audit all four before blaming the model.

Four kinds of agents

Category determines what an agent is allowed to touch.

code-modifying

Writes code. Read + Write + Edit + Bash. The only category that mutates the repo.

builder-product

validator-product

meta/

Builds other agents. Creates agents, prompts, skills, hooks. Operates on the agentic layer, not the app.

meta-agent

adw-planner

context

Reads only. Searches, summarizes, returns findings. Never writes.

Explore

doc-scraper

review

Audits. Reads a spec + reads disk state, reports PASS/BLOCK. Never self-certifies its own work.

validator-product

test-creator

An agent that belongs to two categories is doing two jobs. Per One Agent One Prompt One Purpose — split it.

What the agent sees

System prompt is law. User prompt is per-task.

System prompt

The agent's identity

Set once at boot. Applies to every user prompt the agent ever runs. The rules, the constraints, the tone. Mistakes here scale to every execution.

You are builder-product. You implement

ONE task. Read task_get.py output first.

Never write outside filesExpected.

User prompt

The task at hand

Changes every invocation. The orchestrator's brief: task ID, context paths, acceptance criteria. The agent reads this and executes.

Implement task P1-T3. Read

AGENT_SYSTEM.md and the TDD §2.

Report when filesExpected match disk.

Most engineers will never touch the system prompt — they just write user prompts (Commands). You touch the system prompt when you're building a custom agent — that's where the Agent primitive earns its keep.

The create/don't-create test

Agent vs Command. Draw the line on reuse.

create an agent when

Agent earns the overhead

• You need a specific model (Opus for hard planning)
• You need restricted tools (validators: read-only)
• Role is reused across many workflows
• The agent will be spawned by other agents (delegation)

use a Command instead when

Agent is overhead

• It's a one-off workflow you invoke directly
• Default tools + default model are fine
• No other agent will spawn it
• Scope is a single slash-command invocation

The discipline

An agent is a focused role, not a generalist worker.

One job per agent. Minimum tools. Declared model. The agent you can't describe in one sentence is doing two jobs — split it. Mistakes in the system prompt scale to every run; mistakes in category scale to every workflow that spawns it. Focus is the whole point.