Repository navigation
feat(skills): storefront API contract, revised skills from 17 builds, and storefront, seo-geo, agentic-commerce and media skills - #35
Merged
Conversation
Discovery for every catalogue read, the Shop API for everything about a shopper, Catalogue only for per-customer price display, Core never in the request path. Token and scope tables per API, variantGroups and variant(selected:) in SKILL.md, generated field names, unset booleans reading false, paths per language for hreflang and sitemaps, draft preview through Discovery (and that drafts are public on an open Discovery), and a new discovery-indexing reference on ignite, propagation and consistency. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Shopper writes go through the Shop API from the server, Core is for the back office, PIM for setup. Which store an order goes to and which call creates it (createFromCart, Shop create, registerOrder only for imports), B2B orders on behalf of a company, a server-only checkout flow, webhooks for revalidation, the unit-bound numerics rule, and partial-write traps. Media moves to its own skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Getting images and video in reliably: choosing the way in, copyRemoteAsset limits (timeout, URL length, Content-Length, bot protection), a seven-step import pipeline with verification, presigned uploads, metadata per language, replacing and deleting, showcases, and a failure-mode table. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The quick start uses discoveryApi; catalogueApi and the Catalogue-based helpers are the fallback. Shop callers are server only, token defaults are stated, "Shop or Core?" matches the order rules, and the raw calls for subscription contracts and booking admin are documented where no helper exists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…op API The umbrella skill: the API contract once, credentials and what may run in the browser, a task-to-API decision table, the request path per page type (listing with variantGroups, product page with variant(selected:), search, cart, checkout), caching and the publish webhook, translated paths, B2B prices against a public Discovery, draft preview, and references for performance, accessibility, security headers, i18n routing, cart and checkout, and Next.js pitfalls. Points at superfast.shop for reference implementations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
JSON-LD per page type from typed data (QuantitativeValue with UN/CEFACT codes, classification codes as CategoryCode, ProductGroup, offers with and without VAT, relations), llms.txt, llms-full.txt and Markdown twins, robots for AI crawlers with Content-Signal, metadata in <head> for every user agent (with the Cache Components / PPR pitfall and curl checks), sitemaps with hreflang and updatedAt, and a tested schema.org vocabulary check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Three surfaces on one code path: a shopper-facing MCP server on Discovery and the Shop API (tool design, typed-spec filters parsed from text, "Did you mean", the cartId hand-off, checkout as a destructive tool), OAuth sign-in, MCP Apps cards with host detection, WebMCP (early preview), and an on-site assistant. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Discovery for list and market prices (public when open), the Shop API for the cart's customer, Catalogue for displaying any customer's price. Customer row in the cart context, compare-at and rounding rules, price lists that work at volume, the full Discovery price-field table, and promotion traps. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renewal orders follow the tenant's order store (registerOrder or Shop create from orderIntent), Shop endpoint traps, and every call on the server. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Discovery for the pool and policy snapshot, Shop /cart for availability, holds and confirmation, /order for the order, /booking/admin (booking and booking:admin scopes) for staff, Core for setup. Seven storefront rules from four builds, and booking-flow and modelling additions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The cartId is the session, a signed hand-off lets the browser adopt the basket, an agent never pays card. Core reads labelled webhook-only, Shop customers, lock keys, and the non-tenant-scoped token rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… traps Write taste sequentially and read it back, userTaste as a list, rebuild taste from Shop order history on the server for agents, house ranking when signed out, and ranking once per query. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
og:image and JSON-LD use the original format, never AVIF, at least 1200 px. Derive only from URLs the API returned, one or two high-priority images, the LCP image in the static shell, and two bugs fixed in without-react.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New typed-specs reference (units to schema.org with UN/CEFACT codes, unit lists breaking writes, unset switches reading false). sku, gtin and mpn are separate fields. One plain-text SEO piece without a canonical field. Discovery vs Catalogue follows the storefront contract. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ang and redirects Paths per language from one aliased Discovery query by itemId (replacing the Catalogue recipe), BCP 47 tags and x-default, sitemaps joined on itemId, history redirects, canonicals for shortcuts, re-slugging and collision rules, menus and breadcrumbs from Discovery. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ETIM, GS1 GPC, UNSPSC and Google category codes in topic meta map to JSON-LD CategoryCode. updateTopic without pathIdentifier re-slugs; translate one depth level at a time. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion gaps The real resourceIdentifier charset, where errors live, validation differences, second-language upserts emptying shared relations, large variant sets, and throughput. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…essing Dimensions as numerics with units, stop and ask instead of picking the closest option, and create the language version before translating. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tables written as HTML come back from Discovery as semantic table nodes; it is the App that drops rows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Shop JWTs minted on the server from a pair that is not tenant-scoped, per tenant not per shopper; Discovery open by default and public when open; Core never in the request path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New legacy-apps reference: app.create, the signature query parameter, frame-ancestors and tenant frontends. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New tenant-setup reference: which API creates each setting, getMany shapes, first ignite, storefront credentials and publish webhooks. A Serve step in SKILL.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
agentic-commerce, media, seo-geo and storefront. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add references/preview.md: the custom view and its placeholders, the responsive device toolbar always on (no preview chrome in the storefront), a preview route that checks a secret and resolves the item per language from its draft, draft reads through Discovery switched inside the cached client, no caching and noindex, the App's listener script, framing by https://app.crystallize.com only on preview responses, SameSite=None; Secure; Partitioned cookies, and pitfalls. The storefront skill's draft-preview section links to it, and security-headers gains the preview exception to deny-framing-everywhere. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The findings now say "one build", "another tenant" and similar instead of naming customers. Crystallize's own demo tenants (tools-universe and the other *-universe stores) are kept. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The upload case still expected mutation/media, which is now a pointer to the media skill. Seven new cases cover media, storefront, seo-geo and agentic-commerce. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
seo-geo and responsive-images stated the same rule but their helpers differed: bestImage ignored the 1200 px floor, shareImage did not check for an AVIF upload, and neither returned dimensions. Both now carry the same helper, which falls back to the original upload with its own width and height. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…talogue's Tested on a sandbox tenant: restricting Search & Discovery restricts the Search API at once and Discovery after a re-ignite, while Catalogue stays open. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Minor bumps for the eleven changed skills that kept their version, and metadata for content-json, which had none. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tenant Tested on a sandbox tenant: a tenant-scoped pair minted a Shop JWT for its tenant (200) and was refused for another tenant its user belongs to, with 400 "User is not a member of tenant X". The skills said a tenant-scoped pair could not mint at all, and told storefronts to use an unscoped token. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tested on a sandbox tenant: the Search & Discovery setting reaches the Search API at once but Discovery only after igniteDiscoApi, and anonymous calls then flapped for about four minutes. The skills told users to restrict Discovery without saying so, and called the access token pair unverified; it was refused in both modes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…strict their read APIs Tested on a sandbox tenant: a guest cart that sent a contract market got the contract price, and Discovery gave it anonymously. Pricing, storefront, cart-checkout and agentic-commerce now say that a market identifier works as a key, and recommend restricting Catalogue and Search & Discovery when a tenant has price lists or contract prices. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hop /order is the default Tested on a sandbox tenant: one registerOrder and three updateOrder calls left four Shop orders with one coreId, while a Shop-born order was rewritten in place. Core and Shop /order are meant to work on one order, so the skills now call the copies a reported bug with a workaround, and explain that Shop /order is the asynchronous FIFO entry built for volume while Core is synchronous and rate limited. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A component update replaces shared (non-translated) components in every language, not only the one sent. - A restricted Catalogue answers 400 Invalid static auth token, and takes effect at once. - Shop /auth/token refuses Python's default urllib User-Agent (Cloudflare 1010). - additionalInformation: null fails with a bare Output validation error. - market.create refuses customers that don't exist yet. - priceLists and tenant(identifier:) are unions; registerOrder answers OrderConfirmation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ool descriptions Discovery stays the default for storefront reads, but it is updated asynchronously after a publish. Catalogue is the fallback for per-customer prices and for reads that must be in sync with a publish. The query-catalogue tool still called Catalogue a storefront API for building frontends; both tool descriptions now follow the contract. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Revises the skills from the findings of 17 Crystallize builds, and adds four skills for building storefronts. Each skill has its own commit, as in #32, so the PR reads best commit by commit.
Why
Developers and agents need to know which API does what in a storefront. The skills either didn't say, or said it in ways that contradicted each other. Across the builds, the same mistakes kept coming back:
The source is a proposal built from every build's
skill-findings.md. It cross-checks the findings and the existing skills, and lists 15 contradictions between skills (C1–C15), which this PR resolves.The storefront API contract (now stated in query, mutation and storefront)
variantGroups/variant(selected:), paths per language for hreflang, list and market prices, stock, ranking, and draft preview (publicationState: draft).Verified on live tenants (2026-11-12, reads only)
publicationState: draftreturned 541 hits on tools-universe with and without credentials, so confidential or embargoed content must not sit in drafts on an open tenant.…PriceFor(marketIdentifiers)returned a contract list without a token./booking/adminneeds bothbookingandbooking:admin.booking:adminalone is refused.itemId.false.What changed
querydiscovery-indexingreferencemutationmedia(new)copyRemoteAssetlimits, presigned uploads, video, showcases, failure modesjs-api-clientdiscoveryApi; Catalogue helpers as fallback; Shop callers server only; raw calls where no helper existsstorefront(new)seo-geo(new)<head>for every user agent, sitemaps with hreflang, a tested schema.org checkagentic-commerce(new)pricingsubscriptionsbookable-resourcespaymentsvector-rankingresponsive-imageswithout-react.mdbugs fixedcontent-modeltyped-specsreference; sku, gtin and mpn as separate fields; one plain-text SEO pieceinformation-architecturetaxonomymass-operations,data-creation,content-json,permissions,plugins,agent-tenantslegacy-appsandtenant-setupreferencesMatching docs
The same structure is published at https://crystallize.com/docs/developer/storefront (18 pages).
Not done here
Checks
make codeclean: clean on the changed files. It also reformats about 19 unrelated MCP server files that already drift onmain; those changes are left out of this PR.make tests: 232 pass, 0 fail.🤖 Generated with Claude Code