--- name: agent-builder description: "Guide the operator through authoring a new worker agent: a job-titled specialist that owns one deliverable and the skills that produce it. Activate when the operator asks to add, build, or hire a worker agent, or says 'add an agent that does X'. Composes skill-builder for the agent's skills and hands install to specialist-management." --- # Agent Builder Invoked by the admin agent directly. A conversational walkthrough for authoring a new vertical worker agent the way the reference agents are built: a named deliverable, a fixed contract, a minimal tool allowlist, a chosen model, and the skills it owns. Be conversational, one question at a time, like `skill-builder`. This skill authors the agent. It does not install machinery of its own: it composes `skill-builder` for each skill the agent bundles, and hands the finished file to `specialist-management` for the `cp` plus `AGENTS.md` wiring. ## When to Activate The operator asks to add, build, or hire a worker agent ("add an agent that quotes jobs", "give me a negotiator", "build a worker that does X"). For installing or removing an agent that already exists, that is `specialist-management`; for a standalone capability with no agent of its own, that is `skill-builder`. ## Before Starting Load `references/agent-pattern.md`. It is the canonical shape: the two kinds of agent, the deny-by-default tool rule, model-choice guidance, and the three-part contract body. Use it throughout. Do not paraphrase the pattern from memory; the reference is the source. ## Step 0: Check for a deliverable catalogue When the operator asks what can be built here, rather than naming a specific agent, first look for a shipped suggestion catalogue. A premium bundle can ship a `DELIVERABLES.md` at its root listing deliverables it supports beyond the agents it already ships. Get the enabled bundles from `capabilities-here`, then for each one read `$PLATFORM_ROOT/../premium-plugins//DELIVERABLES.md` if it exists, the bundle root where its `BUNDLE.md` and `agents/` live. Offer the operator the entries you find, grouped by bundle. If no enabled bundle ships one, skip this step and go to Step 1. The catalogue is a suggestion list, not a shipped roster. Each entry is authored bespoke for this account when the operator picks it, because a generic version carries none of the customer's own determinism. On a pick, run Steps 1 through 7 to author the skill and agent into the account's own plugins tree, and name the agent for the customer's actual deliverable rather than the catalogue's ontology label, exactly as the catalogue instructs. The ontology name is grounding, not a file name. ## Step 1: Name the deliverable Ask: **"What is the one thing this agent hands back?"** A vertical agent owns a single deliverable: a priced quote, an interim valuation, a buyer package. If the honest answer names several unrelated things, that is several agents, not one. Say so, and build them one at a time. This is the same split the real-agent bundle made when it broke a single manager into `negotiator`, `valuer`, `compliance`, and `listing-curator`. The deliverable becomes the agent's identity and its `description` dispatch rule. ## Step 2: Choose a name and model Propose a job-titled name with the deliverable in it (`quoter`, `valuer`, `payroll-clerk`). Lowercase, hyphenated. Confirm with the operator. Then choose the model from the work, per `agent-pattern.md`: a heavier model for synthesis, drafting, and judgement; a lighter one for retrieval, lookups, and deterministic roll-ups. State the choice and why. ## Step 3: Decide the skills it owns Ask what skills produce the deliverable. For each one: - **It already exists.** Reference it by name and plugin. - **It needs building.** Run the `skill-builder` flow inline to author it now, under one plugin name you reuse across the agent's skills, so the agent and its skills land together. Collect the skills into the "skills owned" table: the skill, its plugin, and when it runs. ## Step 4: Derive the tool allowlist Read each owned skill and list the tools it actually calls. The agent's `tools` allowlist is the union of those, and nothing more: deny-by-default. A vertical agent never inherits a horizontal specialist's whole surface. Name every tool explicitly; an unused tool is a boundary given away. ## Step 5: Compose the agent file Using `agent-pattern.md`, compose the complete `.md`: 1. **Frontmatter.** `name`, `description` (the dispatch rule), `summary` (one plain line), `model` (chosen in Step 2), `tools` (the Step 4 allowlist). 2. **Body.** The agent's doctrine and identity, then the three contract sections in order with their exact headings: `## Output contract`, `## Review gates`, `## Untrusted input`. The untrusted-input line is the one canonical sentence from `agent-pattern.md`, verbatim. A headless agent with no operator checkpoint carries the untrusted-input line alone. 3. **Skills owned.** The table from Step 3. Show the operator the complete file and ask them to review. ## Step 6: Install through specialist-management The agent persists as part of an admin-managed plugin: the same durable home `store-skill` uses, so it survives a reinstall and the agent and its skills stay together. `store-skill` already created that plugin when you built the agent's skills (canonical under the account, mirrored under the platform plugins tree). Write the composed file, named `{plugin}--{name}.md`, into the plugin's `agents/` directory in both places, so it is durable under the account and immediately visible in the platform mirror that `specialist-management` reads. Then follow `specialist-management`'s "Activate premium plugin agents" path to copy it into `specialists/agents/` and append the `- **specialists:{name}**: {description}` line to the admin `AGENTS.md`. Do not invent install logic; drive that existing path. If the agent bundles only existing skills, so no plugin was created, scaffold the plugin first the way `store-skill` does (a `PLUGIN.md` and the `.user-mirror` marker in both the account and mirror trees) before writing the agent file. ## Step 7: Confirm Tell the operator: > "Your agent `{name}` is saved as part of the `{plugin}` plugin and wired into the roster. It > is active from the next session start. The admin will dispatch it as `specialists:{name}` when > the work matches its description." --- **Remember:** Be conversational. One question at a time. The pattern lives in `references/agent-pattern.md`; load it and follow it, do not reconstruct it from memory.