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

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.

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

安装与使用

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

npx skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-agentic-image-alt-text

技能说明


name: shopify-admin-agentic-image-alt-text role: agentic description: "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." toolkit: shopify-admin, shopify-admin-execution api_version: "2025-01" graphql_operations:

  • products:query
  • fileUpdate:mutation status: stable compatibility: Claude Code, Cursor, Codex, Gemini CLI audit_signals:
  • listing-image-alt-text

Purpose

An AI shopping agent reads image alt text to understand a product's appearance — color, material, style, use. Blank or filename-style alt text ("IMG_2931.jpg") tells the agent nothing, so it can't match the product to a visual query ("red linen midi dress") or describe it to a shopper. This skill finds product images with missing or low-value alt text and writes concise, descriptive alt text derived from the product's title, options, type, and tags. Fixes the agentiq.report finding listing-image-alt-text.

Prerequisites

  • Authenticated Shopify CLI session (shopify auth login --store <domain>)
  • Required API scopes: read_products, write_products, write_files

Parameters

All skills accept these universal parameters:

ParameterTypeRequiredDefaultDescription
storestringyes—Store domain (e.g., mystore.myshopify.com)
formatstringnohumanOutput format: human (default) or json
dry_runboolnofalsePreview mutations without executing

Skill-specific parameters:

ParameterTypeRequiredDefaultDescription
collection_idstringno—Limit to a collection GID
tagstringno—Limit to a product tag
overwriteboolnofalseIf true, also rewrite filename-style / placeholder alt text; if false, only fill blanks
max_charsintno125Alt-text length cap (accessibility + agent-readability)

Safety

⚠️ Step 3 (fileUpdate) writes alt text to live media. With overwrite: true it replaces existing alt text, which is not bulk-reversible. Run dry_run: true first and review the proposed alt text per image. Default (overwrite: false) only fills blanks and is low-risk.

Workflow Steps

  1. OPERATION: products — query Inputs: first: 250, optional collection/tag filter; fields title, productType, tags, options, media{ MediaImage{ id image{ altText } } }; paginate until done. Expected output: Product media with current alt text + the product context needed to generate good alt text.

  2. COMPUTE (no API): for each image with blank (or, if overwrite, placeholder) alt text, compose alt text from title + relevant option values (color/material/style) + product type, trimmed to max_chars. Emit a preview table (image id → proposed alt).

  3. OPERATION: fileUpdate — mutation Inputs: files: [{ id: <MediaImage id>, alt: <generated alt> }] in batches (≤ 25). Expected output: Updated files; collect userErrors.

GraphQL Operations

# products:query — validated against api_version 2025-01
query AltTextProducts($first: Int!, $after: String, $query: String) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        productType
        tags
        options { name values }
        media(first: 20) {
          edges {
            node { ... on MediaImage { id image { altText url } } }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}
# fileUpdate:mutation — validated against api_version 2025-01
mutation AltTextUpdate($files: [FileUpdateInput!]!) {
  fileUpdate(files: $files) {
    files { ... on MediaImage { id alt } }
    userErrors { field message code }
  }
}

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: count of images updated + a CSV (product, image_id, old_alt, new_alt). json: { images_updated, images_skipped, errors, output_file }.

Error Handling

ErrorCauseRecovery
THROTTLEDAPI rate limitWait 2s, retry up to 3 times
userErrors non-emptyInvalid file id / not a MediaImageLog message, skip, continue
Alt exceeds limitGenerated text too longTrim to max_chars at a word boundary

Best Practices

  • Lead the alt text with the concrete noun + distinguishing attribute ("Charcoal merino crew-neck sweater"), not marketing fluff — that's what agents match on.
  • Keep `overwrite
阅读完整来源 ↗