shopify-admin-agentic-organization-schema

SkillCommerce & finance

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.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the shopify-admin-agentic-organization-schema skill

What this skill tells your AI

The instructions your AI receives, as published by 40rty-ai/shopify-admin-skills in skills/agentic/shopify-admin-agentic-organization-schema/SKILL.md and read by ahel’s review.

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

OPERATION: shop — query Inputs: none Expected output: Shop name, primary domain, contact email — the core Organization fields.
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.
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:

{
  "skill": "<skill-slug>",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "metric_key": 0,
    "errors": 0,
    "output_file": null
  }
}

Output Format

human: the generated JSON-LD + the layout diff showing the one inserted render line. json: { theme_id, json_ld, layout_modified: true|false, wrote: true|false, errors }.

Error Handling

Error	Cause	Recovery
`THROTTLED`	API rate limit	Wait 2s, retry up to 3 times
`ACCESS_DENIED`	Missing `write_themes`	Abort; output the snippet so it can be pasted manually
`userErrors` on layout upsert	Liquid syntax issue	Write the snippet only, skip the layout edit, surface the manual `{% render %}` instruction

Best Practices

Only put REAL, official URLs in sameAs — a wrong profile undermines trust rather than building it. Wikipedia/Wikidata links are especially strong identity signals.
Inject via a snippet + a single managed render line; never paste JSON-LD inline into theme.liquid so re-runs and rollback stay clean.
Use an absolute, HTTPS logo URL (a square PNG works best for knowledge panels).
Duplicate the theme first and keep dry_run: true until you've read the layout diff.

Signals

GitHub stars: 187
Forks: 18
Last commit: Aug 2026

ahel review

S4info
community integration — published by 40rty-ai, not shopify

Automated review, not a security audit. Ruleset v1.

Advanced

Catalog kind: skill
Gateway key: shopify-admin-agentic-organization-schema
Source: github.com/40rty-ai/shopify-admin-skills

github.com/40rty-ai/shopify-admin-skills

More in Commerce & finance

agent-payment-x402
Skill · affaan-m customer-billing-ops
Skill · affaan-m finance-billing-ops
Skill · affaan-m disclaimers
Skill · thedaviddias Braintree Automation
Skill · composiohq post-exploitation
Skill · ed1s0nz