shopify-admin-agentic-policy-readability

name	shopify-admin-agentic-policy-readability
role	agentic
description	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.
toolkit	shopify-admin, shopify-admin-execution
api_version	2025-01
graphql_operations	["shop:query","shopPolicyUpdate:mutation"]
status	stable
compatibility	Claude Code, Cursor, Codex, Gemini CLI
audit_signals	["shipping-policy-readable","returns-policy-readable"]

Purpose

Before an AI agent completes a purchase for a shopper it checks the store's policies — "Do they ship to me? What's the return window?" If shipping/returns policies are missing, empty, or buried in an image/PDF, the agent can't answer, loses confidence, and abandons or sends the shopper elsewhere. This skill audits the store's policies and ensures the key ones exist as clean, plain-text/HTML content an agent can read and quote. Fixes shipping-policy-readable and returns-policy-readable.

Prerequisites

• Authenticated Shopify CLI session (shopify auth login --store <domain>)
• Required API scopes: read_legal_policies (or read_online_store_pages), write_legal_policies

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 proposed policy bodies without writing (defaults ON — edits live store policies)

Skill-specific parameters:

Parameter	Type	Required	Default	Description
policies	string	no	REFUND_POLICY,SHIPPING_POLICY	Comma list of policy types to ensure: REFUND_POLICY,SHIPPING_POLICY,PRIVACY_POLICY,TERMS_OF_SERVICE
mode	string	no	audit	audit (report gaps only) or apply (write supplied/drafted bodies)
bodies_dir	string	no	—	Directory of <POLICY_TYPE>.html files to use as the source of truth when mode: apply

Safety

⚠️ Step 2 (shopPolicyUpdate) replaces a LIVE legal policy's body — this is legally binding content. NEVER auto-generate legal text. In mode: apply the skill only writes bodies you supply via bodies_dir; it will not invent policy language. Default is mode: audit + dry_run: true. Have legal/ops review every body before mode: apply.

Workflow Steps

1. OPERATION: shop — query Inputs: none; read shopPolicies { type body url } Expected output: Which target policies are present, empty, or image-only (heuristic: very short body or body that's just an <img>/link).

2. COMPUTE (no API): classify each policy as OK / missing / thin / image-only. In audit mode, stop here and report. In apply mode, load the matching <TYPE>.html from bodies_dir for each gap and emit a before/after preview.

3. OPERATION: shopPolicyUpdate — mutation (only in mode: apply, not dry_run) Inputs: shopPolicy: { id: <policy id>, body: <supplied HTML> } per gap. Expected output: Updated policy; collect userErrors.

GraphQL Operations

# shop:query — validated against api_version 2025-01
query PolicyAudit {
  shop {
    shopPolicies {
      id
      type
      body
      url
    }
  }
}

# shopPolicyUpdate:mutation — validated against api_version 2025-01
mutation PolicyUpdate($shopPolicy: ShopPolicyInput!) {
  shopPolicyUpdate(shopPolicy: $shopPolicy) {
    shopPolicy { id type url }
    userErrors { field message }
  }
}

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: a policy table (type, status, length, readable?) + the audit verdict; in apply mode, the before/after for each written policy. json: { policies:[{ type, status, readable }], updated, errors, output_file }.

Error Handling

Error	Cause	Recovery
THROTTLED	API rate limit	Wait 2s, retry up to 3 times
ACCESS_DENIED	Missing write_legal_policies	Stay in audit mode; report gaps for manual fill
bodies_dir missing a type	No supplied body for a gap	Skip that policy, keep it in the gap report

Best Practices

• Default to mode: audit — this skill's main value is finding image-only or empty policies; writing legal text is a human decision.
• Make policies concrete and parseable: state the return window in days, shipping timeframes, and regions in plain sentences — that's what agents quote.
• Avoid image/PDF-only policies entirely; agents (and many shoppers) can't read them.
• Keep the canonical policy text in bodies_dir under version control so re-applying after edits is auditable.