agent-builder

## Project Context

- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
- project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read
that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md`
probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

## 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 pr