跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

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.

40RTY-ai · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add 40RTY-ai/shopify-admin-skills --skill 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:

ParameterTypeRequiredDefaultDescription
storestringyes—Store domain (e.g., mystore.myshopify.com)
formatstringnohumanOutput format: human (default) or json
dry_runboolnotruePreview proposed policy bodies without writing (defaults ON — edits live store policies)

Skill-specific parameters:

ParameterTypeRequiredDefaultDescription
policiesstringnoREFUND_POLICY,SHIPPING_POLICYComma list of policy types to ensure: REFUND_POLICY,SHIPPING_POLICY,PRIVACY_POLICY,TERMS_OF_SERVICE
modestringnoauditaudit (report gaps only) or apply (write supplied/drafted bodies)
bodies_dirstringno—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

ErrorCauseRecovery
THROTTLEDAPI rate limitWait 2s, retry up to 3 times
ACCESS_DENIEDMissing write_legal_policiesStay in audit mode; report gaps for manual fill
bodies_dir missing a typeNo supplied body for a gapSkip 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 i
阅读完整来源 ↗