---
name: customize
description: Use when the user wants to create or manage a Specialist agent or create, revise, publish, or delete a Skill through the conversational `/Customize` entry. Routes Skill work to the internal skill-creator and handles Specialist work through the JavaScript host.agents SDK.
license: Apache-2.0
---

# Customize

This Skill routes conversational customization to one of two native composers. It is **not a security
boundary**: it helps the user draft, review, confirm, and report changes, while the application decides
whether a destructive or identity-affecting operation actually takes effect.

> Important: this is a framework Skill, not hard isolation. Do not claim that this Skill provides hard
> security isolation; it is workflow guidance only.

## Route first

- For creating, revising, publishing, inspecting, or deleting a Skill, call
  `host.skills.read('skill-creator')` and follow that internal Skill completely. Do not duplicate its
  authoring workflow here.
- For creating or managing a Specialist, follow the Specialist workflow below.
- For a combined request, create or revise the Skill first. After publish and read-back, attach it to
  the selected Specialist only when the user requested that relationship.

Do not create a plan record for Specialist or Skill CRUD. Ask only about choices that materially change
behavior, access, or safety. Skills and Specialists are application-managed resources, not Artifacts.

## Specialist runtime

The Skill runs in the **JavaScript control-plane REPL only**. It uses JavaScript exclusively. Do not
use Python or R here, and do not look for `host.agents` or `host.skills` in a data kernel — they are
absent there. Specialist mutation happens through `host.agents.*`; Skill lifecycle work is delegated
to the internal Skill Creator above.

The Skill never uses the following, and you must not invent them:

- Do not use a Customize Specialist/Profile (there is no such profile).
- Do not use a management MCP tool, and do not route `host.agents` through `host.mcp()`.
- Do not create per-Specialist environments.
- Do not perform duplicate operations (no duplicate Specialist or duplicate operation).
- Do not automatically retry declined or stale privileged operations.

## The `host.agents` SDK surface

The SDK is name-first and lives in the trusted calling session. JavaScript methods, inputs, and
returned records all use camelCase. Methods:

- `host.agents.list()` — custom Specialist summaries for discovery and selection only.
- `host.agents.get(name)` — one existing Specialist's complete current state by immutable name
  (returns stable `id` and `revision`, but you do not show those to the user).
- `host.agents.create(input)` — object form (see below).
- `host.agents.update(name, patch)` — `name` selects the Specialist and is immutable; use
  `patch.displayName` to change its presentation label.
- `host.agents.switch(nameOrNull)` — switches the **current conversation** only; `null` returns to Main
  Agent. Does not accept a caller-supplied session id.
- `host.agents.delete(name, { revision })`.
- `host.agents.attachSkill(name, skillRef, { revision })` / `host.agents.detachSkill(...)`.
- `host.agents.attachConnector(name, connectorRef, { revision })` /
  `host.agents.detachConnector(...)`.
- `host.agents.listSkills(nameOrId?)` — complete Skill catalog, including Main-disabled Skills.
- `host.agents.listConnectors(nameOrId?)` — public Connector information; never credentials, headers,
  environment values, Connector arguments, or tokens.

`create` takes an object:

```js
host.agents.create({
  name,
  displayName,
  description,
  systemPrompt,
  iconKey,
  colorKey,
  enabled,
  unrestricted,
  skillNames,
  connectorNames
})
```

Skill/Connector references resolve an exact stable catalog id first, otherwise a unique immutable name. An
ambiguous name is rejected — tell the user to use the stable id from `listSkills`/`listConnectors`.

Errors are sanitized and prefixed `host.agents.<method>:`; they never contain system instructions,
credentials, headers, environment values, Connector arguments, or the RPC token.

## Specialist identity and composition

Treat `systemPrompt` as the Specialist's identity override while the application's safety, tool, and
workflow rules remain in force. Lead with `You are {displayName}.`, replacing `{displayName}` with
the proposed display name. State the Specialist's one focused job, what it handles, and what the
Specialist does not do. Keep the identity concise; the heavy how-to lives in Skills, not in the system
prompt. Reuse or create Skills for recurring procedures instead of copying those procedures into the
identity.

After a newly created Specialist exists and its state has been read back, offer to switch this
conversation to it with `host.agents.switch(name)`. Do not switch unless the user accepts the offer and
the application approves the privileged operation.

## Workflow — every operation

Follow this order for every mutation. Do not snapshot catalog contents
into a profile or session (resolution is always live):

1. **Understand scope.** What does the user want to create/change/delete/switch?
2. **Live read.** Use `list` for discovery and selection. For an existing Specialist, call `get(name)`
   to read its complete current state. Also call `listSkills`/`listConnectors` to read the catalogs
   before proposing anything.
   Resolve persisted Custom Connector UUIDs through the live Connector catalog and use each
   Connector's immutable `name` in drafts, reviews, and mutation inputs. Never show a Connector UUID
   in ordinary prose. Bundled Connector IDs already equal their names; do not invent suffixes.
3. **Complete draft.** Build the full target state, not a partial edit.
4. **Review.** Show the complete target state to the user.
5. **Applicable confirmation.** Get the confirmation that matches the operation kind (see below).
6. **Mutate.** Call the SDK with the reviewed revision.
7. **Read-back.** After a mutation, re-read actual state with `get(name)`. After delete, verify absence
   with `list` or an expected not-found result from `get(name)`. For switch, use binding read-back.

## Scope clarification (Full vs Selected)

When the user has **not** specified Full versus Selected, you must **ask**. Do not silently use the
SDK's omitted-fields Full default — never assume Full access. Full is selected only after an explicit
request such as "full access" or "same capabilities as Main."

Capability semantics:

- `create` with neither `skillNames` nor `connectorNames` → Full access. But only use this after the
  user explicitly chose Full.
- Supplying either array on `create` → Selected; an omitted other array becomes empty.
- `update({ unrestricted: true })` → Full, preserving the stored Selected configuration.
- Supplying `skillNames` or `connectorNames` to `update` exactly replaces the supplied collection and
  switches to Selected; an omitted collection is preserved.
- `attachSkill`/`detachSkill` and `attachConnector`/`detachConnector` mutate the current mode without
  changing it (Selected: add/remove an inclusion;
  Full: remove/add an exclusion).
- Selected mode with zero Skills and zero Connectors is valid.

## Ordinary mutation review

For create and non-name update, show the complete target state and wait for the user's explicit
confirmation before executing. The review must show:

- Name
- Description
- Full system instructions (shown in the conversation here — they are never written to logs or
  catalog broadcasts)
- Icon and color
- Enabled state
- Full/Selected mode
- Skills
- Whole Connectors
- **Connector tool scope is not configured in this milestone.** State this explicitly — do not show it
  as an empty reviewed configuration. (Per-Connector tool scope arrives in a later milestone.)

For an update, also identify the changed fields.

For multi-field capability edits, prefer **one atomic `update`** over a loop of attach/detach calls
that could partially succeed. Use `attachSkill`/`detachSkill` or
`attachConnector`/`detachConnector` only for a single incremental collection move.

## Confirmation boundaries

- **Create and update:** show the complete target state and wait for the user's
  explicit confirmation (for example "yes", "confirm", "ok") before executing. The initial `/customize`
  entry and the composer prefill are **not** confirmation. `name` is immutable; `displayName` is an
  ordinary update field. The whole patch is applied atomically, and a stale revision fails without
  merge or retry.
- **Delete, switch:** describe the impending action, then execute it directly. These operations are
  privileged and pass through the app's approval card.

When you describe one of these privileged actions, explain:

- **Switch:** current Specialist, target Specialist or Main Agent, the current conversation, and that
  approval lets the current control tool finish before execution automatically continues under the
  approved identity.
- **Delete:** the Specialist name, and that conversations still bound to it become unavailable (they are
  NOT switched to Main Agent).

## Revision and stale drafts

Carry the reviewed `revision` into `update`, `delete`, and the attach/detach methods. A stale revision
fails **without merge or retry**. When it fails, re-read, rebuild the complete draft, and ask for
confirmation again. A changed draft also invalidates the user's earlier confirmation — re-review after
the user edits the draft. Do not automatically retry declined or stale privileged operations.

## Structured declines

A declined operation is a normal result, for example `{ status: "declined", operation: "switch" }`.
Report it as a **user decision** and stop. Do not retry it.

## Read-back and reporting

- After a successful create/update, re-read with `get(name)` and report the actual state. Never assume
  success from the call alone.
- After `switch`, report that approval lets the **current control tool finish**, then automatically
  continues the same task under the approved target. A decline leaves the current Agent unchanged.
  The binding survives app restart.
- After `delete`, report that existing conversations bound to the deleted Specialist become
  **unavailable** — they are not switched to Main Agent; the user must explicitly choose another
  Specialist or Main Agent. Verify deletion with `list` or an expected not-found `get(name)` result.

## Do not expose UUIDs/revisions in ordinary prose

Returned records include stable `id` and `revision`, but do not show them to the user unless needed to
resolve ambiguity (for example, an ambiguous catalog name where you must ask for the stable id) or to
explain a revision conflict. Ordinary reporting uses names and the reviewed state only.

## Language

Respond naturally in the conversation's language. This document and the fixed user-facing review/card
copy remain English.