Agentic Commerce Generate Alt Text

Purpose

Most Shopify catalogs have | no | — | Specific products to process. If omitted, processes all products with image alt-coverage = 5) | | model | string | no | claude-sonnet-4-6 | Vision-language model to use |

Workflow Steps

1. Identify target images: query products via [agentic-commerce-audit-images-alt](../../catalog-audit/agentic-commerce-audit-images-alt/SKILL.md). Collect image URLs + product context.

1. For each image needing alt text:

• Fetch the image bytes
• Send to the chosen vision model with prompt:

``` Generate a concise alt text (under {max_length} chars) for this product image. Product title: {title} Vendor: {vendor} Product type: {productType}

Rules:

• Describe what is visually present in the image
• Include color, material, perspective (front/side/lifestyle) when visible
• Do not invent specs that are not visible
• No marketing language; factual description only

```

• Capture the response

1. OPERATION: fileUpdate (Shopify Files API, for product images) or productImageUpdate — mutation (only if dry_run: false)

1. Output report: per-product, before/after alt-text coverage %, total images updated.

Safety

> ⚠️ Mutations gated behind dry_run: true by default. Vision models can describe images incorrectly (especially for niche or low-quality images). Recommend dry_run first, review a 10% sample, then run with dry_run: false on the full batch. > > Token costs: ~$0.001-0.003 per image with Claude Sonnet vision. A 500-product catalog (avg 5 images) costs ~$5-15 to fully process. Use a cheaper model (Gemini Flash or GPT-4o-mini) for cost reduction at a small quality trade-off.

GraphQL Operations

# productImageUpdate:mutation — validated against api_version 2025-01
mutation ImageAltUpdate($id: ID!, $altText: String!) {
  productImageUpdate(image: { id: $id, altText: $altText }) {
    image {
      id
      altText
    }
    userErrors {
      field
      message
    }
  }
}

Reference

The "what counts as good alt text" rules come from the images dimension of METHODOLOGY.md. Re-run the alt-text audit after fixes to measure score uplift.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: commerce-agentic
• Source: commerce-agentic/agentic-commerce-skills
• License: MIT

Install and usage instructions live in the source repository linked above.