agent-builder

## Guidance Location

The authoritative agent-authoring guidance ships in this plugin. Read the
specific document a decision needs, when that decision is on the table — never
read them all up front, because that defeats progressive disclosure and burns
context on guidance the current agent does not touch.

- Plugin-building guidance root: `${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/`
- Agent-specific guidance: `${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/agent-building-guidelines/`

Map from decision to governing document (read just-in-time):

| Decision on the table | Read |
|---|---|
| Agent vs. skill vs. hook; one role (generate or evaluate) | `plugin-entity-taxonomy.md`, `agent-building-guidelines/agent-domain-focus.md` |
| Domain focus, vocabulary, role identity, anti-patterns | `agent-building-guidelines/agent-domain-focus.md` |
| The `description` field (four components, boundaries, length) | `agent-building-guidelines/agent-description-length.md`, `skill-building-guidance/skill-description-frontmatter.md` |
| Model tier (`opus` / `sonnet` / `haiku` / `inherit`) | `agent-building-guidelines/agent-model-selection.md`, `specialization-and-model-selection.md` |
| Self-containment — no references, scripts, or context injection | `agent-building-guidelines/agent-external-files.md` |
| Which frontmatter fields are valid (and which plugins ignore) | `agent-building-guidelines/agent-external-files.md` |
| Degraded environments (no git, missing tools) | `agent-building-guidelines/graceful-degradation.md` |
| Whether this agent is justified at all; how it gets dispatched | `agent-building-guidelines/multi-agent-economics.md`, `skill-building-guidance/agent-dispatch-namespacing.md` |
| New plugin needed (plugin.json, marketplace.json) | `claude-marketplace-and-plugin-configuration/` and `templates/` |

## Operating Principles

- **Interview relentlessly, but explore first.** Interview the user relentlessly
  about every aspect of the agent until you reach a shared understanding. Walk
  down each branch of the design tree, resolving dependencies between decisions
  one-by-one. **If a question can be answered by exploring the repository — the
  target plugin's existing agents, sibling descriptions, the skills that would
  dispatch this agent, conventions, the guidance documents above — explore
  instead of asking.** Only surface questions that genuinely require the user's
  judgment.
- **Ask one question at a time.** Never batch questions. Settle one decision,
  let its answer resolve dependent decisions, then ask the next. Later answers
  routinely make earlier questions moot.
- **Recommend, then ask.** For every question surfaced to the user, provide a
  recommended answer with rationale grounded in evidence (existing agents,
  conventions, the guidance, the user's stated goal). The user can accept,
  amend, or redirect.
- **Apply guidance as you go, then verify at the end.** Consult the governing
  document when a decision is on the table (Step 4), and run a full
  guidance-conformance pass over the finished agent at the end (Step 6). The
  interview gets each decision approximately right; the review pass makes the
  artifact correct.
- **An agent is self-contained.** Unlike a skill, an agent is a single flat
  `.md` file. No `references/` folder, no `scripts/` folder, no `` !`command` ``
  context injection. Everything the agent needs is inlined in its body.

# Build an Agent

## Step 1: Capture the Request and Confirm It Is an Agent

Read the user's argument and the conversation to extract what the agent should
do. If the request is too thin to start (for example, just "build an agent"),
ask the user for one or two sentences on the agent's domain and what it produces
— nothing else yet.

**Confirm the entity type before anything else.** Read
`${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/plugin-entity-taxonomy.md` and
apply its decision heuristic. An agent is the thinking layer: it applies
contextual judgment, taste, and discernment ("Does this require reasoning about
context?" → agent). If the work is a deterministic, flowchartable process, it is
a skill — stop and recommend `skill-builder`. If it fires automatically on an
event, it is a hook.

**Confirm the single role.** An agent generates **or** evaluates, never both,
because self-evaluation bias means the reasoning that created a blind spot also
rates it as correct (`agent-domain-focus.md`). If the request bundles generation
and evaluation, recommend splitting it into a generator agent and a separate
evaluator agent. Only proceed once an agent — with one role — is the right
entity.

## Step 2: Discover Before Asking

Locate the target plugin and learn its conventions before asking the user
anything beyond the framing. Use Glob, Grep, and `find` to gather:

- The target plugin directory and its `.claude-plugin/plugin.json`. Confirm the
  plugin actually ships agents (an `agents/` directory) or is the right home for
  the first one. If the user has not said which plugin, infer candidates and
  confirm in Step 4.
- Sibling agents in that plugin (`{plugin}/agents/*.md`) — their descriptions,
  role identities, model tiers, domain vocabulary, and the boundaries they draw.
  A new agent's description must disambiguate against near-sibling agents in
  both directions.
- The skills that would dispatch this agent. An agent is dispatched by a skill
  via the `Agent` tool using the qualified `defining-plugin:agent-name`. Knowing
  the caller tells you what the agent receives and returns.
- Whether any step depends on a tool (git, a CLI) that may be absent at dispatch
  time, which drives graceful-degradation wording.

Record what was found (file paths) and what was not.

## Step 3: Build the Design Tree

Enumerate the decisions the agent needs, in dependency order. Resolve
foundational decisions before dependent ones; never ask a dependent question
before its parent is settled.

1. **Foundational** — Which plugin owns it? What is