From shopify-plugin
Guides defining Shopify Metafields and Metaobjects via TOML in shopify.app.toml for custom app data modeling, using GraphQL for values. For Metafields/Metaobjects prompts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/shopify-plugin:shopify-custom-dataThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<critical-instructions>
REMEMBER!!! Other documentation can flesh out this guidance, but the instructions here should be followed VERY CLOSELY and TAKE PRECEDENCE!
# shopify.app.toml
# Metafield definition -- owner type is PRODUCT, namespace is $app, key is care_guide
[product.metafields.app.care_guide]
type = "single_line_text_field"
name = "Care Guide"
access.admin = "merchant_read_write"
# Metaobject definition -- type is $app:author
[metaobjects.app.author]
name = "Author"
display_name_field = "name"
access.storefront = "public_read"
[metaobjects.app.author.fields.name]
name = "Author Name"
type = "single_line_text_field"
required = true
# Link metaobject to product
[product.metafields.app.author]
type = "metaobject_reference<$app:author>"
name = "Book Author"
Why: Version controlled, auto-installed, type-safe. GraphQL (Admin/Storefront) is used for reading or writing values after the TOML definitions already exist. Fields/objects can be edited by merchants when access.admin = "merchant_read_write" is set.
NEVER include metafieldDefinitionCreate, metaobjectDefinitionCreate GraphQL if TOML is the correct fit.
NEVER, EVER show these unless strictly required:
metafieldDefinitionCreate, metaobjectDefinitionCreate[metaobjects.app.example...] in shopify.app.toml, MUST be accessed using type: $app:example[product.metafields.app.example] MUST be accessed using namespace: $app and key: example
namespace: app. This is profoundly incorrect.ALWAYS use metafieldsSet to write metafields. namespace should normally be excluded as the default is $app.
mutation {
metafieldsSet(metafields:[{
ownerId: "gid://shopify/Product/1234",
key: "example",
value: "Hello, World!"
}]) { ... }
}
ALWAYS use metaobjectUpsert to write metaobjects.
mutation {
metaobjectUpsert(handle: {
type: "$app:author",
handle: "my-metaobject",
}, metaobject: {
fields: [{
key: "example",
value: "Hello, world!"
}]
}) { ... }
}
Metafields are accessed via their owning type (e.g. a Product). namespace should normally be excluded as the default is $app.
jsonValue where possible as it better serialises complex types# Admin API
query {
product(id: "gid://shopify/Product/1234") {
example: metafield(key: "example") {
jsonValue
}
}
}
# Storefront API
query {
product(handle: "wireless-headphones-1") {
example: metafield(key: "example") {
value
}
}
}
# Admin API
query {
metaobjects(type: "$app:author", first: 10) {
nodes {
handle
example: field(key: "example") {
jsonValue
}
}
}
}
# Storefront API
query {
metaobjects(type: "$app:author", first: 10) {
nodes {
handle
example: field(key: "example") {
value
}
}
}
}
DO: Access app-owned metafields directly (NO network call):
function Extension() {
// ESSENTIAL: Register this metafield in `shopify.extension.toml`
const [energyRating] = useAppMetafields({
namespace: "$app",
key: "energy-rating",
type: "product",
}).filter((entry) => entry.target.id === productVariantId);
}
DON'T: Make network calls for app-owned metafields.
Use the GraphQL input query to select metafields to load:
query Input {
cart {
lines {
merchandise {
__typename
... on ProductVariant {
example: metafield(namespace: "$app", key: "example") {
jsonValue
}
}
}
}
}
}
Docs: Metafields & Metaobjects
shopify app init, shopify app generate extension, shopify app dev, shopify app deploy.shopify-use-shopify-cli.npx claudepluginhub anthropics/claude-plugins-official --plugin shopify-ai-toolkitDefines and populates agentic-commerce metafields (material, attributes, key features, specs, sizing) so AI agents can filter and match products to shopper requirements.
Integrates Shopify metaobjects as CMS for homepage and marketing pages in shop templates. Adds GraphQL queries for cms_homepage and cms_page, transforming to domain types.
Manages Shopify product catalogs: products, variants, options, collections, metafields, metaobjects, inventory, bulk operations, taxonomy, media via GraphQL API.