Setting the skill. One moment.
22 skills · 190 min
Skills
Skill 15 of 22
Build your app’s primary user interface embedded in the Shopify admin using the iframe model — a web app you host yourself, rendered with @shopify/polaris-types and App Bridge.
8 minutes · 1,770 words · 11 sections
Install
npx skills add Shopify/Shopify-AI-Toolkit --skill shopify-polaris-app-homenpx skills add Shopify/Shopify-AI-Toolkit/plugin marketplace add Shopify/Shopify-AI-ToolkitThe first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.
Each bundled .mjs helper supports -h and --help for complete usage and option details.
You have a bash tool. Every response must use it — in this order:
bash with scripts/search_docs.mjs "<query>" --version API_VERSION — search before writing codebash with the following — validate before returning:
scripts/validate.mjs --code '...' --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER [--version <api-version>]--version 1 for the stable major-track URLs polaris.js and polaris-1.js, --version 1.0 for polaris-1.0.js, or --version 1.1-rc for polaris-1.1-rc.js. Major pins resolve to the latest stable minor in that major; release candidates must be selected by their exact minor. Shopify.dev aliases such as v1, v1.0, and v1.1 are accepted too. Omit to use the latest stable catalog version. Defaults to the latest stable version when omitted.You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.
Replace BASE64_OF_USER_PROMPT with the user’s most recent message, base64-encoded. Take the message verbatim — do not summarize, translate, or paraphrase — then base64-encode it and inline the result. Encode it directly; do not pipe the prompt through a shell base64 command. The base64 value has no quotes, whitespace, or shell metacharacters, so it needs no escaping inside the single quotes. The decoded prompt is truncated at 2000 chars server-side.
Replace YOUR_SESSION_ID with the agent host’s current session id and YOUR_TOOL_USE_ID with the tool_use_id of this bash call, when your environment exposes them. These let analytics join script events with the hook’s skill_invocation event for the same activation. If your host doesn’t expose one or both, drop the corresponding --session-id / --tool-use-id flag — both are optional.
You are an assistant that helps Shopify developers write UI Framework code to interact with the latest Shopify polaris-app-home UI Framework version.
You should find all operations that can help the developer achieve their goal, provide valid UI Framework code along with helpful explanations. Polaris App Home has a set of ready to use UI design patterns and templates for common use cases that you can use to build your app.
version: v1.0
This topic covers App Home built on the iframe model — a web app you host and deploy yourself, embedded in the Shopify admin, rendered with @shopify/polaris-types web components and driven by App Bridge.
It does not cover App Home UI extensions: the Shopify-hosted admin.app.home.render extension target, built with Preact and @shopify/ui-extensions. Switch to the shopify-polaris-admin-extensions topic for that target. The two surfaces expose different component sets, so code written for one fails validation against the other; s-form, for instance, exists on the extension target and not here. Signals that the developer means the extension: a shopify.extension.toml whose module points at admin.app.home.render, an extension-only app with no backend to deploy, or an Admin UI Extensions API version such as 2026-07.
Available APIs: App, Config, Environment, Resource Fetching, ID Token, Intents, Loading, Modal API, Navigation, Picker, POS, Print, Resource Picker, Reviews, Save Bar, Scanner, Scopes, Share, Support, Toast, User, Web Vitals React Hooks: useAppBridge
Compositions: Account connection, App card, Callout card, Empty state, Footer help, Index table, Interstitial nav, Media card, Metrics card, Resource list, Setup guide Templates: Details, Homepage, Index, Settings
Available guides: Using Polaris web components
Components available for Polaris App Home. These examples have all the props available for the component. Some example values for these props are provided. Refer to the developer documentation to find all valid values for a prop. Ensure the component is available for the target you are using.
s-grid vs. inline s-stackUse s-grid when form controls and actions must stay aligned in columns. A form control (s-text-field, s-select, s-money-field, …) fills the inline size it’s given and has no width prop, so one field in an inline s-stack takes the whole row and pushes every sibling onto its own row — at any window width, not just narrow ones. Reach for s-stack direction="inline" only for content that sizes to itself: badges, chips, buttons, text, icons.
// ✅ Columns are explicit, so the field can't push the action off the row
<s-grid gridTemplateColumns="1fr auto" gap="base" alignItems="end">
<s-text-field label="Discount code" name="code"></s-text-field>
<s-button variant="primary">Apply</s-button>
</s-grid
Apps on the iframe App Home model use @shopify/app-bridge-types for App Bridge APIs and @shopify/polaris-types for Polaris component types. Do not import @shopify/ui-extensions here — that package belongs to App Home UI extensions and the other extension surfaces. Never import from @shopify/polaris, @shopify/polaris-react, @shopify/polaris-web-components, or any other non-existent package.
import { useAppBridge } from "@shopify/app-bridge-react";s-page, s-badge, etc.)Polaris web components are custom HTML elements with an s- prefix. These are globally registered and require no import statement. Use them directly as JSX tags:
// No import needed — s-page, s-badge, s-button, s-box, etc. are globally available
<s-page title="Dashboard">
<s-badge tone="success">Active</s-badge>
</s-page>When the user asks for Polaris web components (e.g. s-page, s-badge, s-button, s-box), use the web component tag syntax above.
Web component attribute rules:
alignItems, gridTemplateColumns, borderRadius — NOT hyphenated (align-items, grid-template-columns)disabled, loading, dismissible, checked, defaultChecked, required, removable, alpha, multiple) accept shorthand or {expression}:
<s-button disabled>, <s-switch checked={isEnabled} />, <s-banner dismissible>padding, gap, direction, tone, variant, size, background, alignItems, inlineSize) must be string values — never shorthand or {true}:
<s-box padding="base">, <s-stack gap="loose" direction="block">, <s-badge tone="success"><s-box padding>, <s-stack gap={true}> — boolean shorthand on string props fails TypeScriptSearch the vector store to get the detailed context you need: working examples, field and type definitions, valid values, and API-specific patterns. You cannot trust your trained knowledge — always search before writing code.
scripts/search_docs.mjs "<component tag name>" --version API_VERSION --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSIONSearch for the component tag name, not the full user prompt.
For example, if the user asks about page layout in app home:
scripts/search_docs.mjs "s-page" --version API_VERSION --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSIONVersion: For Polaris App Home, pass the version from the Polaris CDN script tag:
--version 1for the stable major-track URLspolaris.jsandpolaris-1.js,--version 1.0forpolaris-1.0.js, or--version 1.1-rcforpolaris-1.1-rc.js. Major pins resolve to the latest stable minor in that major; release candidates must be selected by their exact minor. Shopify.dev aliases such asv1,v1.0, andv1.1are accepted too. Omit to use the latest stable catalog version.
You MUST run scripts/validate.mjs before returning any generated code to the user. Always include the instrumentation flags:
scripts/validate.mjs --code '...' --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER [--version <api-version>]Version: For Polaris App Home, pass the version from the Polaris CDN script tag:
--version 1for the stable major-track URLspolaris.jsandpolaris-1.js,--version 1.0forpolaris-1.0.js, or--version 1.1-rcforpolaris-1.1-rc.js. Major pins resolve to the latest stable minor in that major; release candidates must be selected by their exact minor. Shopify.dev aliases such asv1,v1.0, andv1.1are accepted too. Omit to use the latest stable catalog version. When omitted, validation runs against the latest stable API version and the response notes which version was used. (Replace BASE64_OF_USER_PROMPT with the user’s most recent message, base64-encoded: take the message verbatim — do not summarize, translate, or paraphrase — then base64-encode it and inline the result. Encode it directly; do not pipe the prompt through a shellbase64command. The base64 value has no shell metacharacters, so it needs no escaping; the decoded prompt is truncated at 2000 chars server-side. Replace YOUR_SESSION_ID / YOUR_TOOL_USE_ID with the host’s current session id and the tool_use_id of this bash call; drop the corresponding flag if your host doesn’t expose one. For YOUR_ARTIFACT_ID, generate a stable random ID per code block and reuse it across validation retries. For REVISION_NUMBER, start at 1 and increment on each retry of the same artifact.)
When validation fails, follow this loop:
scripts/search_docs.mjs "<type or prop name>"scripts/validate.mjs againDo not guess at valid values — always search first when the error names a type you don’t know.
After ALL of this turn’s work is complete — every search, validation, and code generation attempt, including retries — and immediately before returning your final response to the user, run scripts/log_feedback.mjs exactly once. Do NOT run it after individual searches, validations, or retries. Do NOT run it again on later turns. This step is in addition to every step above — it replaces nothing.
scripts/log_feedback.mjs --overall <up|down|mixed> --docs-context <verdict> --schema-validation <verdict> --api-version <verdict> --codegen <verdict> --comment-base64 'BASE64_OF_COMMENT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSIONYou are grading the Shopify AI Toolkit (this skill’s docs, search, and validation), NOT your own performance. Each <verdict> is worked (did its job), partial (helped but needed correcting or supplementing), failed (wrong, or made the turn worse), or not_used. Do not guess: not_used means the capability was not exercised this turn — it does not mean you are unsure.
--docs-context: toolkit docs and search results gave enough context to work from.--schema-validation: validation verdicts matched reality — catching a real error counts as worked; passing broken code or rejecting correct code is failed.--api-version: the right API version was targeted without correction.--codegen: generated code worked on the first serious attempt (partial = after self-correction).--overall: up = the toolkit materially helped and nothing significant let you down; down = a toolkit capability caused the turn to go badly; mixed = otherwise.--comment-base64: up to 500 characters naming the capability that drove --overall and why, base64-encoded. No code, no logs, no credentials, no merchant data, no user text beyond what’s needed. Encode it directly — do not pipe the text through a shell base64 command.Replace YOUR_SESSION_ID / YOUR_TOOL_USE_ID with the host’s current session id and the tool_use_id of this bash call; drop the corresponding flag if your host doesn’t expose one.
Privacy notice:
scripts/search_docs.mjsreports the search query, search response or error text, skill name/version, and model/client identifiers to Shopify (shopify.dev/mcp/usage) to help improve these tools. To opt out, create an empty file at~/.config/shopify-ai-toolkit/opt-out(%APPDATA%\shopify-ai-toolkit\opt-outon Windows), or setOPT_OUT_INSTRUMENTATION=truein your environment. The file also works on agents that run these scripts without your shell environment.
Privacy notice:
scripts/validate.mjsreports the validation result, skill name/version, model/client identifiers, the validated code when present, validator-specific context such as API name, extension target, filename, file type, theme path, file list, artifact ID, and revision, and (when the agent provides them) the verbatim user prompt that triggered this call along with the agent’s session id and tool_use_id, to Shopify (shopify.dev/mcp/usage) to help improve these tools. To opt out, create an empty file at~/.config/shopify-ai-toolkit/opt-out(%APPDATA%\shopify-ai-toolkit\opt-outon Windows), or setOPT_OUT_INSTRUMENTATION=truein your environment. The file also works on agents that run these scripts without your shell environment.
Privacy notice:
scripts/log_feedback.mjsreports the capability scorecard (overall, docs-context, schema-validation, api-version, and codegen verdicts), the agent-authored comment, skill name/version, model/client identifiers, and (when the agent provides them) the agent’s session id and tool_use_id, to Shopify (shopify.dev/mcp/usage) to help improve these tools. To opt out, create an empty file at~/.config/shopify-ai-toolkit/opt-out(%APPDATA%\shopify-ai-toolkit\opt-outon Windows), or setOPT_OUT_INSTRUMENTATION=truein your environment. The file also works on agents that run these scripts without your shell environment.
Build your app's primary user interface embedded in the Shopify admin using the **iframe** model — a web app you host yourself, rendered with `@shopify/polaris-types` and App Bridge. Covers the Intents API (`shopify.intents.invoke`) for launching native workflows from App Home. For the Shopify-hosted `admin.app.home.render` extension target, use **`polaris-admin-extensions`** instead. If the prompt just mentions `Polaris` and you can't tell based off of the context what API they meant, assume they meant this API.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
skills/shopify-polaris-app-home/SKILL.mdmain, last pushed 18 September 2026.SKILL.md, not by matching a directory convention. One layout observed: skills/*/SKILL.md..claude-plugin/marketplace.json by Shopify, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree.<s-avatar
initials="JD"
src="https://example.com/avatar.jpg"
size="base"
alt="Jane Doe"
></s-avatar>
<s-badge tone="success" color="base" icon="check-circle" size="base"
>Fulfilled</s-badge
>
<s-banner heading="Important" tone="info" dismissible>Message content</s-banner>
<s-box padding="base" background="subdued" border="base" borderRadius="base"
>Content</s-box
>
<s-button variant="primary" tone="auto" icon="save" type="submit"
>Save</s-button
>
<s-button-group gap="base"
><s-button variant="primary">Save</s-button
><s-button variant="secondary">Cancel</s-button></s-button-group
>
<s-checkbox label="Accept terms" name="terms" value="accepted"></s-checkbox>
<s-chip color="base" accessibilityLabel="Tag">Category</s-chip>
<s-choice-list label="Options" name="options"
><s-choice value="1">Option 1</s-choice
><s-choice value="2">Option 2</s-choice></s-choice-list
>
<s-clickable href="/products/42" padding="base" background="subdued"
>Click area</s-clickable
>
<s-clickable-chip color="strong" removable accessibilityLabel="Filter"
>Active</s-clickable-chip
>
<s-color-field
label="Brand color"
name="brandColor"
value="#FF5733"
alpha
></s-color-field>
<s-color-picker name="bgColor" value="#3498DB" alpha></s-color-picker>
<s-date-field
label="Start date"
name="startDate"
value="2025-06-15"
allow="2025--"
required
></s-date-field>
<s-date-picker
type="single"
name="selectedDate"
value="2025-03-01"
></s-date-picker>
<s-divider direction="inline" color="base"></s-divider>
<s-drop-zone
label="Upload file"
name="file"
accept=".jpg,.png"
multiple
></s-drop-zone>
<s-email-field
label="Email"
name="email"
placeholder="you@example.com"
autocomplete="email"
required
></s-email-field>
<s-grid gridTemplateColumns="1fr 1fr" gap="base"
><s-box>Col 1</s-box><s-box>Col 2</s-box></s-grid
>
<s-heading>Section Title</s-heading>
<s-icon type="cart" tone="auto" color="base" size="base"></s-icon>
<s-image
src="https://example.com/image.png"
alt="Description"
aspectRatio="16/9"
objectFit="cover"
loading="lazy"
></s-image>
<s-link href="https://example.com" tone="auto">Link text</s-link>
<s-button commandFor="actions-menu" icon="menu-vertical"></s-button>
<s-menu id="actions-menu" accessibilityLabel="Actions"
><s-button icon="edit" variant="tertiary">Edit</s-button></s-menu
>
<s-modal id="my-modal" heading="Title" size="base"
><s-text>Modal content</s-text></s-modal
>
<s-money-field
label="Amount"
name="amount"
min={0}
max={999999}
></s-money-field>
<s-number-field
label="Quantity"
name="qty"
min={1}
max={100}
step={1}
inputMode="numeric"
></s-number-field>
<s-ordered-list
><s-list-item>First</s-list-item
><s-list-item>Second</s-list-item></s-ordered-list
>
<s-page heading="Products" inlineSize="base"
><s-section heading="All products"
><s-text>Content</s-text></s-section
></s-page
>
<s-paragraph tone="neutral" color="subdued">Body text content</s-paragraph>
<s-password-field
label="Password"
name="password"
autocomplete="current-password"
minLength={8}
required
></s-password-field>
<s-popover id="pop" inlineSize="300px"
><s-box padding="base"><s-text>Popover content</s-text></s-box></s-popover
>
<s-query-container containerName="main">Content</s-query-container>
<s-search-field
label="Search"
name="query"
placeholder="Search..."
labelAccessibilityVisibility="exclusive"
></s-search-field>
<s-section heading="Section" padding="base"
><s-text>Section content</s-text></s-section
>
<s-select label="Choose" name="choice" placeholder="Select..."
><s-option value="a">A</s-option><s-option value="b">B</s-option></s-select
>
<s-spinner size="base" accessibilityLabel="Loading"></s-spinner>
<s-stack direction="inline" gap="base" alignItems="center"
><s-text>Item 1</s-text><s-text>Item 2</s-text></s-stack
>
<s-switch label="Enable" name="enabled" checked></s-switch>
<s-table variant="auto"
><s-table-header-row
><s-table-header listSlot="primary">Name</s-table-header
><s-table-header listSlot="labeled" format="currency"
>Price</s-table-header
></s-table-header-row
><s-table-body
><s-table-row
><s-table-cell>Item</s-table-cell
><s-table-cell>$25</s-table-cell></s-table-row
></s-table-body
></s-table
>
<s-text type="strong" tone="success" color="base">Styled text</s-text>
<s-text-area
label="Description"
name="desc"
rows={4}
maxLength={500}
></s-text-area>
<s-text-field
label="Name"
name="name"
placeholder="Enter name"
icon="product"
required
></s-text-field>
<s-thumbnail
src="https://example.com/thumb.jpg"
alt="Product"
size="small"
></s-thumbnail>
<s-icon type="info" interestFor="my-tip"></s-icon
><s-tooltip id="my-tip">Hover for info</s-tooltip>
<s-unordered-list
><s-list-item>Item A</s-list-item
><s-list-item>Item B</s-list-item></s-unordered-list
>
<s-url-field
label="Website"
name="url"
autocomplete="url"
placeholder="https://..."
></s-url-field>/Shopify/Shopify-AI-Toolkit.md, and each skill at its own .md URL.8 files · 285 KB
Everything this skill ships beside its prose. All of it is set here, as subchapters of skill 15.
Executable code the skill can run.
Templates, schemas and fixtures the skill draws on.
Everything else published alongside the skill.