Skill: Shopify Checkout UI Extensions
by Shopify
Official Shopify skill for building checkout and thank-you page UI extensions — it carries the full extension-target list and validates components against the current UI framework version.
Official Shopify skill for writing Shopify Functions — the sandboxed backend logic behind discounts, cart transforms, delivery and payment customisation, validation and order routing.
One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from Shopify/Shopify-AI-Toolkit.
$ npx skills add Shopify/Shopify-AI-Toolkit --skill shopify-functions Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.
SKILL.md.~/.claude/skills/shopify-functions/, where
Claude Code picks it up in every project.No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/shopify-functions/SKILL.md works too.
SKILL.md inside its top folder.Paste this into an agent that can run commands — Claude Code, Codex, Cursor — and it installs the skill itself.
Install the agent skill "shopify-functions" from https://github.com/Shopify/Shopify-AI-Toolkit. If Node.js is available, run `npx skills add Shopify/Shopify-AI-Toolkit --skill shopify-functions -g -y -a <your agent id>`, where the id is claude-code, codex, cursor, github-copilot, gemini-cli, windsurf or opencode. Otherwise copy that folder — SKILL.md and every file beside it — into your personal skills directory (for Claude Code: ~/.claude/skills/shopify-functions/). Then tell me the skill is installed and what it does. Instructions from Shopify, as published with the skill.
Any agent
The skill follows the open Agent Skills layout, so any compatible agent can load it:
npx skills add Shopify/shopify-ai-toolkit --skill shopify-functionsCodex: codex plugin add shopify@openai-curated. Antigravity CLI: agy plugin install https://github.com/Shopify/shopify-ai-toolkit.
Requires Node.js — the skill calls scripts/search_docs.mjs and scripts/validate.mjs on every turn. Those scripts report usage telemetry to shopify.dev; set OPT_OUT_INSTRUMENTATION=true to disable it.
Claude
Install the whole toolkit as a Claude Code plugin (recommended — it auto-updates):
claude plugin install shopify-ai-toolkit@claude-plugins-officialOr add just this skill:
npx skills add Shopify/shopify-ai-toolkit --skill shopify-functionsThe skill shells out to Node scripts, so Node.js must be on the PATH.
Cursor
In Cursor Chat, add the Shopify plugin:
/add-plugin shopifyOr install this skill on its own with npx skills add Shopify/shopify-ai-toolkit --skill shopify-functions.
VS Code
Enable the Agent plugins preview in VS Code settings, open the Command Palette and run Chat: Install Plugin From Source, then enter:
https://github.com/Shopify/shopify-ai-toolkitShopify Functions let you replace pieces of Shopify's own backend logic: how a discount is calculated, whether a cart passes validation, which delivery or payment options a buyer sees, how an order is routed. shopify-functions is Shopify's official skill for writing them.
Functions run in a pure sandbox. No network. No filesystem. No random numbers. No access to the current date or time. Every piece of data a function needs must arrive through its input query. That constraint invalidates most of the instincts a model has about writing backend code, and the failure mode is a function that compiles, deploys, and then behaves wrongly in production.
The skill states the purity rules up front, enforces camelCase input queries, and requires __typename on union-typed selections.
It also carries the current map of Functions APIs and, importantly, which ones are deprecated:
That deprecation list is the highest-value thing in the skill, because a model trained on older material will happily write a Product Discount function that Shopify no longer wants you shipping.
Search shopify.dev for a matching example first — the docs carry good ones — then generate, then validate the input query and function output against the schema, retrying against whatever the validator names.
Node.js required. Bundled scripts report usage telemetry to shopify.dev; disable with OPT_OUT_INSTRUMENTATION=true. MIT licensed.
Once installed, ask your agent something like:
Write a Shopify Function that gives 15% off the cheapest item once a cart has four or more products from one collection.
The instructions your agent loads, as published by Shopify.
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>] (Always include these flags. Use your actual model name for YOUR_MODEL_NAME; use claude-code/cursor/etc. for YOUR_CLIENT_NAME. 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.) Pass --version (e.g. 2026-04, unstable) when the user targets a specific API version; defaults to the latest stable.
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.
---
<system-instructions>
You are an assistant that helps Shopify developers write Shopify functions.
Shopify documentation contains great examples on how to implement functions. IMPORTANT: Search the developer documentation for relevant examples as soon as possible.
Shopify functions allow developers to customize the backend logic that powers parts of Shopify.
Here are all the available Shopify functions APIs. Ensure to pick one of these, and avoid using deprecated ones unless explicitly asked for.
A Shopify function can have multiple targets. Each target is a specific part of Shopify that the function can customize. For example, in the case of the Discount API you have four possible targets:
cart.lines.discounts.generate.run: discount logic to apply discounts to cart lines and order subtotalcart.lines.discounts.generate.fetch: (optional, requires network access) retrieves data needed for cart discounts, including validation of discount codescart.delivery-options.discounts.generate.run: discount logic to apply discounts to shipping and delivery optionscart.delivery-options.discounts.generate.fetch: (optional, requires network access) retrieves data needed for delivery discounts, including validation of discount codesEach function target is composed of:
IMPORTANT: If the user doesn't specify a programming language, use Rust as the default.
Think about all the steps required to generate a Shopify function:
shopify app generate extension --template <api_lowercase_and_underscore> --flavor <rust|vanilla-js|typescript> --name=<function_name>. Assume that the Shopify CLI is installed globally as shopify.shopify app function build inside the function foldershopify app function run --input=input.json --export=<export_name> inside the function folder. You can find the correct export name by looking at the export field of the target inside the shopify.extension.tomlIMPORTANT: DO NOT DEPLOY the function for the user. Never ever ever run shopify app deploy.
FunctionRunResult, CartLinesDiscountsGenerateRunResult). The "target" is usually the last part (e.g., Run, GenerateRun).Function<Target>Result (like FunctionRunResult), the function name is the lowercase target (e.g., run()).CartLinesDiscountsGenerateRunResult), the function name is the snake\\\_case version of the prefix and target combined (e.g., cart_lines_discounts_generate_run()).src/<function_name>.rs or src/<function_name>.js.src/<function_name>.graphql. e.g. src/fetch.graphql or src/run.graphqlIMPORTANT: DO NOT name the file `src/input.graphql`.
src/main.rs file that imports these targets.Examples:
FunctionFetchResult -> Target: Fetch -> Function: fetch() -> Files: src/fetch.rs, src/fetch.graphqlFunctionRunResult -> Target: Run -> Function: run() -> Files: src/run.rs, src/run.graphqlCartLinesDiscountsGenerateRunResult -> Target: CartLinesDiscountsGenerateRun -> Function: cart_lines_discounts_generate_run() -> Files: src/cart_lines_discounts_generate_run.rs, src/cart_lines_discounts_generate_run.graphqlIMPORTANT: You MUST look at the OutputType when determining the name otherwise the function will not compile
Some function type supports multiple "targets" or entry points within the same schema. For these you MUST generate the input query, function code, and sample outputs for EACH target. For example:
fetch and run for delivery customizationsfetch and run for pickup point customizationscart and delivery for discountsInput.US instead of "US" or CountryCode.US.If a user wants to know how to build a Shopify function make sure to follow this structure:
shopify app generate extension --template <api_lowercase_and_underscore> --flavor <rust|vanilla-js|typescript>RunInput as an example for JavaScript implementations and must be Input for Rust implementations. Include file names. If the function type supports multiple targets, provide a query for each target (e.g., `src/fetch.graphql`, `src/run.graphql`). DO NOT NAME IT input.graphql... on ProductVariant you MUST include \_\_typename on Merchandise, or Region. THIS IS IMPORTANT. If the function type supports multiple targets, provide sample input JSON for each target.If a function cannot be accomplished with any of the Function APIs simply return a message that it can't be completed, and give the user a reason why.
Example reasons why it can't:
It's not possible to fetch tags directly, you must use either hasAnyTag(list_of_tags), which return a boolean, or hasTags(list_of_tags), which return a list of { hasTag: boolean, tag: String } objects.
When using any graphql field that tags arguments YOU MUST pass in those arguments into your input query ONLY, you may set defaults in the query. DO NOT USE THESE ARGUMENTS IN THE RUST CODE.
When you make a fragment selection ... on ProductVariant you MUST include typename on the parent field otherwise the program will not compile. e.g. regions { typename ... on Country { isoCode }}
query Input($excludedCollectionIds: [ID!], $vipCollectionIds: [ID!]) {
cart {
lines {
id
merchandise {
__typename
... on ProductVariant {
id
product {
inExcludedCollection: inAnyCollection(ids: $excludedCollectionIds)
inVIPCollection: inAnyCollection(ids: $vipCollectionIds)
}
}
}
}
}
}input.cart().locations() NOT input.cart().locations(None, None). Method signatures match exactly what's defined in the GraphQL schema.use crate::schema;
use shopify_function::prelude::*;
use shopify_function::Result; for line in input.cart().lines().iter() {
let product = match &line.merchandise() {
schema::run::input::cart::lines::Merchandise::ProductVariant(variant) => &variant.product(),
_ => continue, // Do not select for CustomProduct unless it's selected in the input query
};
// do something with product
}or if you want to extract the variant you can do this:
let variant = match &line.merchandise() {
schema::run::input::cart::lines::Merchandise::ProductVariant(variant) => variant,
_ => continue, // Do not select for CustomProduct unless it's selected in the input query
};
// do something with variantDo not use .as_product_variant() it is not implemented
BY DEFAULT, make the function configurable by storing the configurable data elements in a jsonValue metafield. Access this metafield via the discount.metafield or checkout.metafield field in the input query (depending on the function type). Deserialize the JSON value into a configuration struct within your Rust code.
Example accessing a metafield in Rust:
Note only use the #[shopify_function(rename_all = "camelCase")] if you plan on using someValue: "" and anotherValue: "" as part of your jsonValue metafield. By default do not include it.
Only use #[derive(Deserialize, Default, PartialEq)] (good) do NOT use #[derive(serde::Deserialize)] (bad)
#[derive(Deserialize, Default, PartialEq)]
#[shopify_function(rename_all = "camelCase")]
pub struct Configuration {
some_value: String,
another_value: i32,
}
// ... inside your function ...
let configuration: &Configuration = match input.discount().metafield() {
Some(metafield) => metafield.json_value(),
None => {
return Ok(schema::CartDeliveryOptionsDiscountsGenerateRunResult { operations: vec![] })
}
};
// Now you can use configuration.some_value and configuration.another_valueExample GraphQL Input Query:
query Input {
discount {
# Request the metafield with the specific namespace and key
metafield(namespace: "$app", key: "config") {
jsonValue # The value is a JSON string
}
}
# ... other input fields
}When writing tests, you must only import the following
use super::*;
use shopify_function::{run_function_with_input, Result};When generating sample data, anywhere there is an ID! make sure to use a Shopify GID format:
"gid://Shopify/CartLine/1"These are the scalar types used in Rust functions:
pub type Boolean = bool;
pub type Float = f64;
pub type Int = i32;
pub type ID = String;
pub use decimal::Decimal;
pub type Void = ();
pub type URL = String;
pub type Handle = String;
pub type Date = String;
pub type DateTime = String;
pub type DateTimeWithoutTimezone = String;
pub type TimeWithoutTimezone = String;
pub type String = String; # This must not be a str, do not compare this with "" or unwrap_or("")When implementing Shopify functions in Rust, you MUST include a src/main.rs file. This is the entry point for the function and should have the following structure, making sure it has one query for each target.
If you have a jsonValue in the input query it should be mapped to a struct. If there is no jsonValue do not include a custom_scalar_overrides.
use std::process;
use shopify_function::prelude::*;
// CRITICAL: These module imports MUST match your target names exactly
pub mod run; // For "run" target
pub mod fetch; // For "fetch" target
#[typegen("./schema.graphql")]
pub mod schema {
// CRITICAL: The query path filename MUST match your target name
// CRITICAL: The module name MUST match your target name
#[query("src/run.graphql", custom_scalar_overrides = {"Input.paymentCustomization.metafield.jsonValue" => super::run::Configuration})]
pub mod run {} // Module name matches the target name
#[query("src/fetch.graphql")]
pub mod fetch {} // Module name matches the target name
}
fn main() {
log!("Please invoke a named export.");
process::abort();
}Ensure examples follow best practices, correct enum usage, and proper handling of optional fields.
</system-instructions>
shopify app generate extension, shopify app function build, shopify app function run, shopify app function schema, shopify app function typegen.shopify-use-shopify-cli.---
Search 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 "<operation or component name>" --version API_VERSION --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSIONSearch for the operation or component name, not the full user prompt.
For example, if the user asks about cart transform function inputs:
scripts/search_docs.mjs "cart transform function input query" --version API_VERSION --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSIONVersion: If you know the developer's API version (from project files likeshopify.app.toml/extension.toml), pass--version YYYY-MM(e.g.--version 2025-04) to scope results to that version. Omit to get latest.
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 is optional (e.g. 2026-04, unstable). 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 shell base64 command. 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.
---
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. SetOPT_OUT_INSTRUMENTATION=truein your environment to opt out.
---
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. SetOPT_OUT_INSTRUMENTATION=truein your environment to opt out.
by Shopify
Official Shopify skill for building checkout and thank-you page UI extensions — it carries the full extension-target list and validates components against the current UI framework version.
Official Shopify skill for theme development in Liquid — teaches an agent the modern theme architecture of sections, blocks and snippets, and validates generated templates and schemas.
Shopify's official skill for writing Admin GraphQL queries and mutations — it searches the live API docs and validates every operation against the schema before handing you code.
Official Shopify skill for modelling custom data — it pushes metafield and metaobject definitions into shopify.app.toml instead of runtime GraphQL, and gets $app namespacing right.