agent-builder

## When to use

Invoke this skill when the user asks you to:

- Create a new specialised agent (e.g., "build me a daily standup digester").
- Wire a schedule, webhook, or app event to an agent so it fires
  autonomously.
- Attach a skill or MCP server to an agent you (or the user) own.
- Request a missing capability before performing a gated action.

Do NOT invoke this skill for:

- Editing the system prompt of an already-published agent — that
  requires forking; the UI handles it.
- Publishing an agent to the marketplace. Publishing is a UI-only
  action that flips `is_published=True` after a human review. There is
  no `publish_agent` tool.

## Hard rules — read before any tool call

1.  **Depth-1 cap.** You can create child agents and attach schedules
    to them, but those children cannot themselves spawn grandchildren.
    The `attach_schedule` tool rejects depth-2 attempts with code
    `depth_exceeded`. The DB also enforces `depth IN (0, 1)` as a
    second line of defence.
2.  **Drafts only.** Every agent and automation you create starts in
    DRAFT state:
    - `MarketplaceAgent.is_published=False` — invisible in the public
      marketplace.
    - `AutomationDefinition.is_active=False` — never fires.
    The user must enable both in the UI before anything goes live.
3.  **Positive-list inheritance.** A child automation's contract MAY
    only carry scopes from this list:
    `tools.execute`, `read_file`, `write_file`, `bash_exec`,
    `web_fetch`, `web_search`, `send_message`, `app.invoke`, plus any
    `mcp.*` prefix. The non-inheritable scopes you can NOT propagate
    include `marketplace.author` and `automations.write` — `attach_schedule`
    rejects child contracts that contain them.
4.  **Budget rollup.** A child automation's `max_spend_per_run_usd`
    must be `<=` the parent's. Daily spend is debited from BOTH the
    child's daily counter AND every ancestor in the parent chain — if
    any counter would go negative the run is paused with
    `paused_reason='parent_budget_exhausted'`. You cannot use a child
    to escape a parent's daily cap.

## The six tools

### `create_agent(name, description, system_prompt, model?, tool_allowlist?)`

Draft a new `MarketplaceAgent` row. Returns `{agent_id, slug, draft_url, is_published: false}`.
The row is owned by the calling user and stamped with
`created_by_automation_id` pointing back to your automation, so the
dispatcher can walk the provenance chain later.

Required scope: `marketplace.author`.

### `update_agent(agent_id, patch)`

Patch whitelisted draft fields. Rejects:

- Published rows (`is_published=True`) — fork via the UI instead.
- Built-in or system rows.
- Any agent the calling user doesn't own.
- The `is_published`, `is_builtin`, `is_system`, `id`, `slug`,
  `pricing_type`, `created_by_*` fields — these are server-managed.

### `assign_skill(agent_id, skill_id)`

Insert an `AgentSkillAssignment` row linking a skill to your agent.
Idempotent on the `(agent_id, skill_id, user_id)` unique constraint —
re-running with the same pair is a no-op.

### `assign_mcp(agent_id, mcp_config_id, scopes?)`

Insert an `AgentMcpAssignment` row linking a user-installed MCP server
to your agent. The `scopes` arg is recorded for audit; the actual
`mcp.*` scope enforcement happens at call time via the automation
contract.

### `attach_schedule(agent_id, trigger, prompt_template, contract, delivery_targets?, workspace_scope?, max_compute_tier?)`

Create a child `AutomationDefinition` that runs the agent on a trigger.

- `trigger` is `{kind, config}` where `kind` ∈
  `{cron, webhook, app_invocation, manual}`.
- `prompt_template` is the body sent to the agent on each run. It can
  reference event payload fields with `{key}` interpolation.
- `contract` is the runtime contract — see "positive-list inheritance"
  and "budget rollup" above. The tool runs the inheritance validator
  before insert; failures surface as
  `contract inheritance violation: <code>: <reason>`.
- `delivery_targets` (optional) is a list of
  `CommunicationDestination` UUIDs. Each must be owned by the calling
  user.
- `workspace_scope` defaults to `user_automation_workspace`. The
  per-user `~automations~` workspace project is lazy-created the first
  time a `user_automation_workspace` automation actually fires — there
  is nothing for you to provision.
- `max_compute_tier` defaults to `0` (no pod). Bump to `1` for
  ephemeral pods or `2` for persistent environments — but only if the
  parent automation's contract allows.

The new automation is created with `is_active=False`. The user must
flip it on in the UI before it starts firing. Required scope:
`automations.write`.

### `request_grant(resource, capability)`

Register an approval card asking the user to grant a capability the
run doesn't currently have. Returns `{approval_id}` immediately. Do
NOT block on the response inside the tool — the agent loop must
checkpoint on the approval id and let the dispatcher resume the run
after the user responds (non-blocking HITL pattern).

`resource` is `{kind, id}`; `capability` is a dotted scope string
(e.g., `mcp.linear.read`).

## Recommended flow

1.  `create_agent` to draft the agent row.
2.  `assign_skill` / `assign_mcp` to attach the dependencies the agent
    will need at runtime.
3.  `update_agent` to refine the system prompt, tool allowlist, or
    metadata as you learn more about what the user wants.
4.  `attach_schedule` to wire a trigger + contract + delivery targets.
5.  Tell the user where to find the draft (`draft_url` from
    `create_agent`) and remind them they need to publish the agent +
    enable the automation from the UI before it goes live.

## Common failure modes

- **`depth_exceeded`** — you're already running inside a child
  automation. Refactor the parent automation to spawn what you need
  directly.
- **`scope_not_inheritable`** — the child contract carries
  `marketplace.author`, `automations.write`, or another
  non-positive-list scope. Drop i