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, 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):

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 the single narrow domain? Generate or evaluate? What does the agent produce, and who dispatches it?
2. Identity — What is the Role Identity, the opening "You are a..." paragraph (under 50 tokens, domain + task + perspective, no flattery)? What 15-30 domain-vocabulary terms pass the 15-year-practitioner test? What 5-10 named anti-patterns with detection signals does the agent hunt for?
3. Triggering — What does the description say across all four components (what, when, boundary, breadth), and how does it disambiguate against near-sibling agents in both directions, within 1024 characters?
4. Capabilities — What model tier fits the cognitive load (opus for synthesis and judgment, sonnet for structured procedures, haiku for fast lookups, inherit only when matching the session is intentional)? What tools does it need, defaulting to no Agent tool, since dispatch flows from skills to agents, and carrying it only when the agent's own protocol dispatches sub-agents?
5. Body structure — What inlined protocol, checklist, and reference content does the agent need to do its job, given it cannot use external files? Where does graceful-degradation wording belong?

Keep each node a concrete decision with a candidate answer. Do not pre-fill the tree with content the user has not confirmed.