/shopify-admin-agentic-organization-schema
Inject an Organization JSON-LD block (name, logo, sameAs social links, contactPoint) into the theme so AI agents can verify the store is a real, trusted brand and link it to its public identity.
$ npx -y skills add 40rty-ai/shopify-admin-skills --skill shopify-admin-agentic-organization-schema --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/shopify-admin-agentic-organization-schema
Context preview
The summary Claude sees to decide when to auto-load this skill.
Inject an Organization JSON-LD block (name, logo, sameAs social links, contactPoint) into the theme so AI agents can verify the store is a real, trusted brand and link it to its public identity.
SKILL.md
shopify-admin-agentic-organization-schema.SKILL.mdname: shopify-admin-agentic-organization-schema
role: agentic
description: "Inject an Organization JSON-LD block (name, logo, sameAs social links, contactPoint) into the theme so AI agents can verify the store is a real, trusted brand and link it to its public identity."
toolkit: shopify-admin, shopify-admin-execution
api_version: "2025-01"
graphql_operations:
- shop:query
- themes:query
- themeFilesUpsert:mutation
status: stable
compatibility: Claude Code, Cursor, Codex, Gemini CLI
audit_signals:
- org-schema
- machine-contact
- wikidata-qid
Purpose
AI assistants check a site's `schema.org/Organization` JSON-LD to confirm it's the real brand (not a counterfeit or reseller) and to connect it to its public identity via `sameAs` (official socials, Wikipedia/Wikidata) and a machine-readable `contactPoint`. Without it, agents hesitate to recommend the store or send buyers to it. This skill builds an Organization JSON-LD block from the shop's data + supplied social links and injects it into the theme layout via a managed snippet. Fixes `org-schema`, `machine-contact`, and supports `wikidata-qid` (through `sameAs`).
Prerequisites
- Authenticated Shopify CLI session (`shopify auth login --store <domain>`)
- Required API scopes: `read_themes`, `write_themes`
Parameters
All skills accept these universal parameters:
| Parameter | Type | Required | Default | Description | |-----------|--------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | format | string | no | human | Output format: `human` (default) or `json` | | dry_run | bool | no | true | Preview the snippet + injection without writing (defaults ON — edits the live theme) |
Skill-specific parameters:
| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | theme_id | string | no | — | Theme GID (defaults to published MAIN theme) | | logo_url | string | no | — | Absolute logo URL (else inferred from theme settings if available) | | same_as | string | no | — | Comma list of official profile URLs (Instagram, TikTok, LinkedIn, Wikipedia, Wikidata) | | contact_email | string | no | — | Customer-support email for `contactPoint` (else shop contactEmail) | | contact_phone | string | no | — | Optional support phone for `contactPoint` |
Safety
> ⚠️ Step 3 (`themeFilesUpsert`) writes a snippet and edits `layout/theme.liquid` in the LIVE theme. The change is additive (a `{% render %}` in `<head>`), but it publishes immediately and a malformed edit to `theme.liquid` can break rendering. The skill writes the JSON-LD into its own snippet file and inserts a single managed `{% render 'agentic-organization-schema' %}` line inside a `# BEGIN/END` marker block. Defaults `dry_run: true`; duplicate the theme first.
Workflow Steps
1. **OPERATION:** `shop` — query **Inputs:** none **Expected output:** Shop name, primary domain, contact email — the core Organization fields.
2. **OPERATION:** `themes` — query **Inputs:** `roles: [MAIN]`, `theme.files(filenames: ["layout/theme.liquid", "snippets/agentic-organization-schema.liquid"])` **Expected output:** Current layout (to inject the render tag) + whether the snippet already exists.
3. **OPERATION:** `themeFilesUpsert` — mutation **Inputs:** write `snippets/agentic-organization-schema.liquid` (the JSON-LD `<script type="application/ld+json">`), and upsert `layout/theme.liquid` with the managed `{% render %}` block added in `<head>` if absent. Skipped on `dry_run`. **Expected output:** Upserted files; collect `userErrors`.
GraphQL Operations
# shop:query — validated against api_version 2025-01
query OrgSchemaShop {
shop {
name
primaryDomain { url }
contactEmail
}
}# themes:query — validated against api_version 2025-01
query OrgSchemaTheme {
themes(first: 1, roles: [MAIN]) {
nodes {
id
files(filenames: ["layout/theme.liquid", "snippets/agentic-organization-schema.liquid"]) {
nodes {
filename
body { ... on OnlineStoreThemeFileBodyText { content } }
}
}
}
}
}# themeFilesUpsert:mutation — validated against api_version 2025-01
mutation OrgSchemaUpsert($themeId: ID!, $files: [OnlineStoreThemeFilesUpsertFileInput!]!) {
themeFilesUpsert(themeId: $themeId, files: $files) {
upsertedThemeFiles { filename }
userErrors { filename code message }
}
}Snippet body (`snippets/agentic-organization-schema.liquid`):
{%- comment -%} managed by shopify-admin-agentic-organization-schema {%- endcomment -%}
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "<shop name>",
"url": "<primary domain>",
"logo": "<logo_url>",
"sameAs": [ "<same_as[0]>", "..." ],
"contactPoint": {
"@type": "ContactPoint",
"contactType": "customer support",
"email": "<contact_email>"
}
}
</script>Session Tracking
**Claude MUST emit the following output at each stage. This is mandatory.**
**On start**, emit:
╔══════════════════════════════════════════════╗
║ SKILL: <skill name> ║
║ Store: <store domain> ║
║ Started: <YYYY-MM-DD HH:MM UTC> ║
╚══════════════════════════════════════════════╝
**After each step**, emit:
[N/TOTAL] <QUERY|MUTATION> <OperationName>
→ Params: <brief summary of key inputs>
→ Result: <count or outcome>If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.
**On completion**, emit:
For `format: human` (default):
══════════════════════════════════════════════
OUTCOME SUMMARY
<Metric label>: <value>
Errors: 0
Output: <filename or "none">
══════════════════════════════════════════════
For `format: json`, emit: `
Read more
name: shopify-admin-agentic-organization-schema role: agentic description: "Inject an Organization JSON-LD block (name, logo, sameAs social links, contactPoint) into the theme so AI agents can verify the store is a real, trusted brand and link it to its public identity." toolkit: shopify-admin, shopify-admin-execution api_version: "2025-01" graphql_operations: - shop:query - themes:query - themeFilesUpsert:mutation status: stable compatibility: Claude Code, Cursor, Codex, Gemini CLI audit_signals: - org-schema - machine-contact - wikidata-qid
Purpose
AI assistants check a site's `schema.org/Organization` JSON-LD to confirm it's the real brand (not a counterfeit or reseller) and to connect it to its public identity via `sameAs` (official socials, Wikipedia/Wikidata) and a machine-readable `contactPoint`. Without it, agents hesitate to recommend the store or send buyers to it. This skill builds an Organization JSON-LD block from the shop's data + supplied social links and injects it into the theme layout via a managed snippet. Fixes `org-schema`, `machine-contact`, and supports `wikidata-qid` (through `sameAs`).
Prerequisites
- Authenticated Shopify CLI session (`shopify auth login --store <domain>`)
- Required API scopes: `read_themes`, `write_themes`
Parameters
All skills accept these universal parameters:
| Parameter | Type | Required | Default | Description | |-----------|--------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | format | string | no | human | Output format: `human` (default) or `json` | | dry_run | bool | no | true | Preview the snippet + injection without writing (defaults ON — edits the live theme) |
Skill-specific parameters:
| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | theme_id | string | no | — | Theme GID (defaults to published MAIN theme) | | logo_url | string | no | — | Absolute logo URL (else inferred from theme settings if available) | | same_as | string | no | — | Comma list of official profile URLs (Instagram, TikTok, LinkedIn, Wikipedia, Wikidata) | | contact_email | string | no | — | Customer-support email for `contactPoint` (else shop contactEmail) | | contact_phone | string | no | — | Optional support phone for `contactPoint` |
Safety
> ⚠️ Step 3 (`themeFilesUpsert`) writes a snippet and edits `layout/theme.liquid` in the LIVE theme. The change is additive (a `{% render %}` in `<head>`), but it publishes immediately and a malformed edit to `theme.liquid` can break rendering. The skill writes the JSON-LD into its own snippet file and inserts a single managed `{% render 'agentic-organization-schema' %}` line inside a `# BEGIN/END` marker block. Defaults `dry_run: true`; duplicate the theme first.
Workflow Steps
1. **OPERATION:** `shop` — query **Inputs:** none **Expected output:** Shop name, primary domain, contact email — the core Organization fields.
2. **OPERATION:** `themes` — query **Inputs:** `roles: [MAIN]`, `theme.files(filenames: ["layout/theme.liquid", "snippets/agentic-organization-schema.liquid"])` **Expected output:** Current layout (to inject the render tag) + whether the snippet already exists.
3. **OPERATION:** `themeFilesUpsert` — mutation **Inputs:** write `snippets/agentic-organization-schema.liquid` (the JSON-LD `<script type="application/ld+json">`), and upsert `layout/theme.liquid` with the managed `{% render %}` block added in `<head>` if absent. Skipped on `dry_run`. **Expected output:** Upserted files; collect `userErrors`.
GraphQL Operations
# shop:query — validated against api_version 2025-01
query OrgSchemaShop {
shop {
name
primaryDomain { url }
contactEmail
}
}# themes:query — validated against api_version 2025-01
query OrgSchemaTheme {
themes(first: 1, roles: [MAIN]) {
nodes {
id
files(filenames: ["layout/theme.liquid", "snippets/agentic-organization-schema.liquid"]) {
nodes {
filename
body { ... on OnlineStoreThemeFileBodyText { content } }
}
}
}
}
}# themeFilesUpsert:mutation — validated against api_version 2025-01
mutation OrgSchemaUpsert($themeId: ID!, $files: [OnlineStoreThemeFilesUpsertFileInput!]!) {
themeFilesUpsert(themeId: $themeId, files: $files) {
upsertedThemeFiles { filename }
userErrors { filename code message }
}
}Snippet body (`snippets/agentic-organization-schema.liquid`):
{%- comment -%} managed by shopify-admin-agentic-organization-schema {%- endcomment -%}
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "<shop name>",
"url": "<primary domain>",
"logo": "<logo_url>",
"sameAs": [ "<same_as[0]>", "..." ],
"contactPoint": {
"@type": "ContactPoint",
"contactType": "customer support",
"email": "<contact_email>"
}
}
</script>Session Tracking
**Claude MUST emit the following output at each stage. This is mandatory.**
**On start**, emit:
╔══════════════════════════════════════════════╗ ║ SKILL: <skill name> ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
**After each step**, emit:
[N/TOTAL] <QUERY|MUTATION> <OperationName>
→ Params: <brief summary of key inputs>
→ Result: <count or outcome>If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.
**On completion**, emit:
For `format: human` (default):
══════════════════════════════════════════════ OUTCOME SUMMARY <Metric label>: <value> Errors: 0 Output: <filename or "none"> ══════════════════════════════════════════════
For `format: json`, emit: `
Community-maintained AI agent skills for operating Shopify stores — workflows, optimization, reports and more
Other skills on shopify-admin-skills.
- /shopify-admin-agentic-crawler-access
Edit the theme's robots.txt.liquid to explicitly allow AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot, Amazonbot) so AI assistants are permitted to read the catalog.
Open skill - /shopify-admin-agentic-description-enrichment
Rewrite thin product descriptions into structured, fact-rich copy (materials, fit, use-cases, the words shoppers actually type) so AI agents have something concrete to quote and match.
Open skill - /shopify-admin-agentic-image-alt-text
Generate and set descriptive alt text on product images so AI agents (which can't 'see' pixels) can understand and recommend what each product looks like.
Open skill - /shopify-admin-agentic-llms-txt
Generate and publish an /llms.txt guide (brand summary, flagship products, key policies, contact) via a theme template so AI assistants get a curated, machine-readable map of the store.
Open skill - /shopify-admin-agentic-metafields-setup
Define and populate agentic-commerce metafields (material, attributes, key features, specs, sizing) so AI agents can filter and match products to specific shopper requirements.
Open skill - /shopify-admin-agentic-policy-readability
Ensure shipping, returns, refund, privacy, and terms policies exist as clean machine-readable text so AI agents can answer shopper questions and close the sale without escalating.
Open skill