version: "1.0.0" name: amplifier-shell description: "Customize Amplifier Unified presentation or build shell extensions. USE WHEN changing layouts, themes, sidebar modules, or artifact viewers, interactive conversation surfaces, and validating hot-loaded components. DO NOT USE WHEN changing AmplifierSession tools, providers, or orchestration; use runtime bundle guidance."

Amplifier Unified shell

Use this skill for the web shell. A shell module changes presentation; an Amplifier behavior changes the agent's runtime configuration. This skill is delivered by a behavior so agents can learn the shell's separate extension API.

Discover the target

1. Read app state using app_control(operation="get_state"). Identify the

user's intended browser client from visibleUI.clientId; never assume a global presentation or choose an arbitrary attached client. Follow $statePath references with bounded reads when the overview omits details.

1. Request current action schemas using `app_control(operation="list_actions",

args={"prefix":"shell."}) and, for artifact views, args={"prefix":"canvas.views."}. Inspect the relevant shell or view before preparing a change. For shell components, use the returned slots, registry, resolvedInstances and componentCommands`; only author against contracts that host exposes. Discover theme actions separately when a CSS skin is requested.

1. If working outside an app session, use the host's authenticated

GET /api/actions and POST /api/actions interfaces through the user's configured connection. If no connection exists, author locally and report activation as unverified. Never read credential files to invent a connection.

Success criteria: An explicit target client and the current supported actions are known, or work is clearly limited to an offline package.

Choose the workflow

• Change existing presentation: Read presentation.md.

Reuse installed modules, layouts and themes before creating code.

• Create interactive UX for a conversation: Read

conversation-surfaces.md. Keep one surface ID and refine its existing tab, preserving shared user/agent state.

• Build or replace a component: Read authoring.md, then the

relevant contract in the shell guide. The public SDK is packages/shell-sdk.

These paths are relative to this skill's directory. The same resource layout is included in installed app packages; a development checkout is not required to read the guide, SDK, or examples. Locate companions relative to the path returned by load_skill, not the conversation's workspace.

Preserve ownership and verify

Use shared actions and the public SDK. Canonical conversations, drafts, sessions, resources and tool execution belong to the host. Keep passive navigation passive. Read-only browsing must not select a chat or send context. Declare unsaved component edits with host.setDirty; retain dirty components until their edits are resolved. Never use recovery to silently discard edits.

Use current revisions and view generations from inspection. Retry uncertain mutations with the same request ID and identical arguments. Validation approval is distinct from activation, and activation is distinct from user acceptance. Finish with the changed client/module/view, browser evidence, preservation checks, and a usable revert path. State any missing live validation explicitly.