Customize Specialists and Skills

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:

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.