Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
6d12a61
fix(skills): query opens with the storefront API contract
papelipe Nov 12, 2026
b14ae21
fix(skills): mutation follows the write side of the contract
papelipe Nov 12, 2026
19e4baf
feat(skills): media, split out of mutation
papelipe Nov 12, 2026
cb65c1a
fix(skills): js-api-client starts from discoveryApi
papelipe Nov 12, 2026
c519294
feat(skills): storefront, building a frontend on Discovery and the Sh…
papelipe Nov 12, 2026
74ea73b
feat(skills): seo-geo, structured data and answer-engine visibility
papelipe Nov 12, 2026
d79e5ad
feat(skills): agentic-commerce, letting AI agents shop the store
papelipe Nov 12, 2026
65d7cbd
fix(skills): pricing says which price comes from which API, for whom
papelipe Nov 12, 2026
ab0c24e
fix(skills): subscriptions follow the order store
papelipe Nov 12, 2026
77b4596
fix(skills): bookable-resources gets an API table and storefront rules
papelipe Nov 12, 2026
609f162
fix(skills): payments covers checkout started by an agent
papelipe Nov 12, 2026
fe09067
fix(skills): vector-ranking adds taste-ranked agent results and write…
papelipe Nov 12, 2026
36a1437
fix(skills): responsive-images covers share and structured-data images
papelipe Nov 12, 2026
4e018f1
fix(skills): content-model settles identifiers, SEO and typed specs
papelipe Nov 12, 2026
34a1930
fix(skills): information-architecture uses Discovery for paths, hrefl…
papelipe Nov 12, 2026
9424a63
fix(skills): taxonomy carries classification codes
papelipe Nov 12, 2026
034c15a
fix(skills): mass-operations documents identifiers, errors and valida…
papelipe Nov 12, 2026
cf9faac
fix(skills): data-creation uses typed numerics and asks instead of gu…
papelipe Nov 12, 2026
ef19106
fix(skills): content-json reconciles tables
papelipe Nov 12, 2026
70be73d
fix(skills): permissions adds storefront credentials
papelipe Nov 12, 2026
2e66e50
fix(skills): plugins documents legacy PIM apps
papelipe Nov 12, 2026
5ed437e
fix(skills): agent-tenants gains tenant setup and serving
papelipe Nov 12, 2026
c93ba35
docs(readme): list the new skills
papelipe Nov 12, 2026
771e9c6
feat(skills): storefront preview with custom views
papelipe Nov 12, 2026
7294873
fix(skills): remove customer and tenant names from build findings
didrikhegna Nov 13, 2026
6a5ba3c
test(mcp): reference eval expects media/import and covers the new skills
didrikhegna Nov 17, 2026
d2156cd
fix(skills): one shareImage for og:image and JSON-LD images
didrikhegna Nov 17, 2026
033b304
fix(skills): Discovery follows the Search & Discovery setting, not Ca…
didrikhegna Nov 17, 2026
8f1e7f0
chore(skills): bump versions of every skill this branch changes
didrikhegna Nov 17, 2026
77aa993
fix(skills): a tenant-scoped token mints Shop API tokens for its own …
didrikhegna Nov 17, 2026
9102ca6
fix(skills): restricting Discovery needs a re-ignite
didrikhegna Nov 17, 2026
8eafe4a
fix(skills): markets come from the server session, and B2B tenants re…
didrikhegna Nov 17, 2026
56ee9c2
fix(skills): order copies after a Core edit are a sync bug, and why S…
didrikhegna Nov 17, 2026
2e2280e
fix(skills): smaller findings from a sandbox tenant
didrikhegna Nov 17, 2026
5e06bf1
fix(skills): Catalogue is the synchronous fallback, also in the MCP t…
didrikhegna Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ bun type-check # TypeScript type checking

Skills are plain markdown files in `use-crystallize/skills/` — no build step required. Each skill has a `SKILL.md` with YAML frontmatter and an optional `references/` directory with supporting docs.

Available skills: `agent-tenants`, `bookable-resources`, `content-json`, `content-model`, `data-creation`, `information-architecture`, `js-api-client`, `mass-operations`, `mutation`, `payments`, `permissions`, `plugins`, `pricing`, `query`, `responsive-images`, `subscriptions`, `taxonomy`, `vector-ranking` — the directory itself is the authoritative list.
Available skills: `agent-tenants`, `agentic-commerce`, `bookable-resources`, `content-json`, `content-model`, `data-creation`, `information-architecture`, `js-api-client`, `mass-operations`, `media`, `mutation`, `payments`, `permissions`, `plugins`, `pricing`, `query`, `responsive-images`, `seo-geo`, `storefront`, `subscriptions`, `taxonomy`, `vector-ranking` — the directory itself is the authoritative list.

## Using the Claude Plugin

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@
},
{
"task": "upload product images from external URLs and attach them to items",
"skills": ["mutation"],
"expected": ["mutation/media"]
"skills": ["mutation", "media"],
"expected": ["media/import"]
},
{
"task": "my bulk task is stuck in running, and how many operations can one file hold?",
Expand Down Expand Up @@ -89,5 +89,40 @@
"task": "create a custom role with the API and assign it to a user",
"skills": ["permissions"],
"expected": ["permissions/role-api"]
},
{
"task": "upload a product video and wait until it has been transcoded",
"skills": ["media"],
"expected": ["media/video"]
},
{
"task": "revalidate product and category pages when an item is published",
"skills": ["storefront"],
"expected": ["storefront/caching-and-revalidation"]
},
{
"task": "build the cart and checkout on the server with the Shop API",
"skills": ["storefront"],
"expected": ["storefront/cart-checkout"]
},
{
"task": "add Product JSON-LD with offers, prices and units to our product pages",
"skills": ["seo-geo"],
"expected": ["seo-geo/json-ld"]
},
{
"task": "publish llms.txt and Markdown versions of our product pages for AI crawlers",
"skills": ["seo-geo"],
"expected": ["seo-geo/llms-and-markdown"]
},
{
"task": "expose our catalogue and cart as an MCP server so AI agents can shop",
"skills": ["agentic-commerce"],
"expected": ["agentic-commerce/mcp-server"]
},
{
"task": "let an AI assistant sign in on behalf of a customer and place an order",
"skills": ["agentic-commerce"],
"expected": ["agentic-commerce/oauth"]
}
]
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,10 @@ export const createQueryCatalogueToolWrapper = ({ tenantMatcher, queryExecutor }
"Execute a GraphQL query against the Crystallize Catalogue API. " +
"If you haven't already, call the `skills` tool first — it provides query examples and best practices " +
"that will help you write correct queries. " +
"The Catalogue API is a storefront API for fetching items, products, and content to build frontends. " +
"Use this for reading specific items by path or ID, traversing the catalogue tree, " +
"and accessing detailed component data with full type support.",
"For storefront reads, prefer the Discovery API. The Catalogue API is the synchronous fallback: " +
"use it for a specific customer's price-list prices (`priceFor(customerIdentifiers)`, server-side only) " +
"and for reads that must be in sync with what was just published, since Discovery is updated asynchronously. " +
"It can also read specific items by path or ID and traverse the catalogue tree.",
inputSchema: z.object({
tenant: tenantSchema,
query: querySchema,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ export const createQueryDiscoveryToolWrapper = ({ tenantMatcher, queryExecutor }
"that will help you write correct queries. " +
"The Discovery API is a storefront API for searching, browsing, filtering, and faceting items and products " +
"to build frontends. It uses a shape-typed schema where each shape in the tenant becomes a GraphQL type. " +
"Use this for searching, filtering, listing items, and aggregating data for storefront use cases.",
"This is the default for every storefront catalogue read: items by path, listings, search, filtering and facets. " +
"It is updated asynchronously after a publish; for a read that must be in sync, or a specific customer's price, use the Catalogue API.",
inputSchema: z.object({
tenant: tenantSchema,
query: querySchema,
Expand Down
40 changes: 33 additions & 7 deletions use-crystallize/skills/agent-tenants/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,20 @@
---
name: agent-tenants
description: >
Get a Crystallize tenant as an AI agent, for a user who has no Crystallize account, and hand it over
to them before it expires. Use when the user has no tenant or no access token and wants the agent to
set one up, asks for a sandbox or demo tenant, or wants an agent-made tenant handed over, claimed or
kept. Trigger on "create a tenant", "new tenant", "set up Crystallize for me", "I don't have a
Get a Crystallize tenant as an AI agent, for a user who has no Crystallize account, hand it over
to them before it expires, and get any new tenant ready to serve a storefront. Use when the user has no
tenant or no access token and wants the agent to set one up, asks for a sandbox or demo tenant, or wants
an agent-made tenant handed over, claimed or kept. Also use when setting up languages, the default
language, VAT types, price variants, stock locations, pipelines, markets or webhooks on a new tenant,
asking "which API creates X" (Core or the legacy PIM API), running the first Discovery ignite, debugging
"There is no ignited Tenant", getting storefront credentials, or wiring publish webhooks for cache
revalidation. Trigger on "create a tenant", "new tenant", "set up Crystallize for me", "I don't have a
Crystallize account", "sign up", "provision", "agent tenant", "/agents/tenants", "hand over the
tenant", "claim the tenant", "invite me", "createInviteToken", "tenantAdmin", "get-access", "tenant
expires", "tenant deleted".
expires", "tenant deleted", "tenant setup", "igniteDiscoApi", "createWebhook".
metadata:
author: Crystallize
version: "1.0"
version: "1.1"
---

# Crystallize Agent Tenants
Expand Down Expand Up @@ -40,9 +44,11 @@ send them one link.
3 Invite createInviteToken(role: "tenantAdmin") → invite token
4 Hand off the App's /get-access?token=… link → the human joins as tenantAdmin
5 Check the tenant's members on the PIM API → a human tenantAdmin = claimed
6 Serve publish, igniteDiscoApi, credentials → a storefront can read it
```

Only step 1 is specific to agents. Steps 2 to 5 are the API a human tenant admin already uses.
Only step 1 is specific to agents. Steps 2 to 6 are the API a human tenant admin already uses, and step 6 applies
to every new tenant.

| Used for | Host |
| ------------------------- | ------------------------------------- |
Expand Down Expand Up @@ -232,6 +238,25 @@ Variables: `{ "id": "6adbb89b790dd26b73debb6b" }` (the `tenant.id` from step 1).
only member is the agent: `role: "tenantAdmin"`, `firstName: "Agent"`, `email: null`, `kind: "agent"`. Once
they join, a second member appears with `role: "tenantAdmin"` and `kind: "human"`, with their name and email.

## 6 · Get it ready to serve

A built tenant is not yet one a storefront can read. Do this before you hand over, or tell the user what is left:

1. **Settings first.** Languages, the default language, VAT types, price variants, stock locations and pipelines
are split between the Core API and the legacy PIM API (same token headers). A fresh tenant already has `en`, a
`No Tax` VAT type, a `default` price variant in EUR and a `default` stock location.
2. **Publish** the items. Discovery indexes only published content, and `publishItem` returns before the item is
published.
3. **Ignite Discovery** once with `igniteDiscoApi(stacks: opensearch)` on the Core API. Until then Discovery answers
HTTP 404 with "There is no ignited Tenant" in a plain JSON body. Ignite again after new shapes, components, stock
locations or vocabularies.
4. **Credentials.** The storefront's server needs the static token if Discovery or Catalogue is restricted, and an
access token pair to mint Shop API tokens (one scoped to the tenant is enough). Core stays out of the request path.
5. **Publish webhooks** (`concern: "items"`, plural) if the storefront caches Discovery reads.

Every setting with its API and call, the `getMany` answer shapes, the ignite, the credentials table and a webhook
example are in [references/tenant-setup.md](references/tenant-setup.md). The storefront side is in [[storefront]].

## Rules

| Topic | Rule |
Expand Down Expand Up @@ -278,5 +303,6 @@ GraphQL calls answer HTTP 200 with the error inside the result union (`__typenam
| An invite with no `expiresAt`, or one past the tenant's | A link that still looks valid after the tenant is gone | Pass the tenant's `expiresAt` |
| Giving the link without the deadline | The user opens it on day four and finds nothing | Always state the date and time with the link |
| Saying "it's yours, nothing to transfer" after provisioning | The user never opens the invite, and the tenant is deleted | The tenant is the agent's until a human `tenantAdmin` joins |
| Handing over without publishing and igniting | The storefront gets "There is no ignited Tenant" or no hits | Publish, `igniteDiscoApi(stacks: opensearch)`, then hand over (step 6) |

Related: [[permissions]] for roles and access tokens once the human owns the tenant.
Loading
Loading